Install
openclaw skills install bambu-studio-aiBambu Lab 3D printer control and automation. Activate when user mentions: printer status, 3D printing, slice, analyze model, generate 3D, AMS filament, print monitor, Bambu Lab, or any 3D printing task. Full pipeline: search → generate → analyze → colorize → preview → open BS → user slice → print → monitor. Supports all 9 Bambu Lab printers (A1 Mini, A1, P1S, P2S, X1C, X1E, H2C, H2S, H2D).
openclaw skills install bambu-studio-aiRequest → Collect Info → Search/Generate → Analyze(11pt) → [Colorize] → Preview(chat) → Open BS → [User Slices in BS] → Confirm → Print → Monitor
Pre-check: If config.json does not exist → run First-Time Setup before any operation.
At the start of each turn: If handling a print request, re-read the Pipeline Checklist and Compliance Rules. Ensure you are not skipping any MUST step.
Before every action, verify you are not violating these rules:
| Rule | Meaning |
|---|---|
| MUST | Non-negotiable. Skip = failure. |
| NEVER | Forbidden. Doing it = failure. |
| WAIT | Do not proceed until user responds. |
generate.pyanalyze.py --orient --repairbambu.py print without user confirmation. AI models have errors.analyze.py --orient --repair on every modelpreview.py --views turntable → send image/GIF to useropen -a "BambuStudio" model.3mf (or model.stl/obj)Note:
slice.py(CLI slicing via OrcaSlicer) is optional — only use if user explicitly requests CLI slicing. The default is for users to slice in Bambu Studio themselves, where they can adjust supports, infill, and other settings visually.
[ ] Info collected (source, dimensions, colors, material)
[ ] Model obtained (search/generate/download)
[ ] analyze.py --orient --repair run
[ ] Preview image/GIF sent to chat
[ ] Opened in Bambu Studio
[ ] User sliced + inspected in Bambu Studio
[ ] User confirmed "looks good" / "print it"
[ ] Print started (only after confirmation)
| I want to... | Command |
|---|---|
| Printer status | python3 scripts/bambu.py status |
| Print progress | python3 scripts/bambu.py progress |
| Printer hardware info | python3 scripts/bambu.py info |
| Start a print | python3 scripts/bambu.py print <file> --confirmed |
| Pause / Resume / Cancel | python3 scripts/bambu.py pause|resume|cancel |
| Speed mode | python3 scripts/bambu.py speed silent|standard|sport|ludicrous |
| Light on/off | python3 scripts/bambu.py light on|off |
| AMS filament info | python3 scripts/bambu.py ams |
| Camera snapshot | python3 scripts/bambu.py snapshot |
| Send G-code | python3 scripts/bambu.py gcode "G28" |
| Notification | python3 scripts/bambu.py notify --message "done" |
| Generate 3D (text) | python3 scripts/generate.py text "desc" --wait --height 80 (--raw skips auto-enhancement; --height sets target mm, default auto 80mm) |
| Generate 3D (image) | python3 scripts/generate.py image photo.jpg --wait --height 80 (auto: validate, bg-remove, prompt enhance; --no-bg-remove / --raw to skip) |
| Download model | python3 scripts/generate.py download <task_id> --height 80 |
| Analyze model | python3 scripts/analyze.py model.stl --height 80 --orient --repair --material PLA (always exports _scaled file when --height is used) |
| Keep main only (remove fragments) | python3 scripts/analyze.py model.stl --repair --keep-main |
| Multi-color | python3 scripts/colorize model.glb --height 80 --max_colors 8 -o out.obj (tunable: --min-pct, --no-merge, --island-size, --smooth, --bambu-map) |
| Slice (optional CLI) | python3 scripts/slice.py model.stl --orient --arrange --quality fine |
| Slice (specific setup, optional) | python3 scripts/slice.py model.stl --printer A1 --filament "Bambu PETG Basic" |
| List slicer profiles | python3 scripts/slice.py --list-profiles |
| Preview (quick) | python3 scripts/preview.py model.stl (--height 80 to verify dimensions) |
| Preview (HQ Blender) | python3 scripts/preview.py model.stl --hq |
| Search models | python3 scripts/search.py "phone stand" --limit 5 |
| Monitor print | python3 scripts/monitor.py --auto-pause |
| Check deps | python3 scripts/doctor.py |
| Parametric box | python3 scripts/parametric.py box 30 20 10 -o box.stl |
| Parametric cylinder | python3 scripts/parametric.py cylinder --radius 5 --height 20 -o cyl.stl |
| Parametric bracket | python3 scripts/parametric.py bracket --width 30 --height 40 --thickness 3 --hole-diameter 3.2 -o bracket.stl |
| Parametric plate with holes | python3 scripts/parametric.py plate-with-holes --width 60 --depth 40 --holes 4 --hole-diameter 3.2 --hole-spacing 25 -o plate.stl |
| Parametric enclosure | python3 scripts/parametric.py enclosure --width 60 --depth 40 --height 30 --wall 2 --lid -o case.stl |
| Parametric CSG (complex) | python3 scripts/parametric.py csg spec.json -o assembly.stl |
All scripts support --help. generate.py auto-enhances prompts and limits size to printer build volume.
User Request
│
▼
Information Collection
│
▼
Decision 1: Model Source
├─ A: Internet Search (preferred default)
├─ B: AI Generate (single-color)
├─ C: AI Generate (multi-color)
├─ D: User-provided file
├─ E: Image to 3D
└─ F: Parametric (functional parts — manifold3d)
│
▼
Model Processing (analyze → repair → orient → [colorize])
│
▼
Report Results to User
│
▼
⛔ Open in Bambu Studio → User Inspects
│
▼
User Confirms ("looks good" / "print it")
│
▼
Decision 2: Print Method
├─ E: Auto Print (Developer Mode only, not recommended)
└─ F: Manual Print (user handles in Bambu Studio)
│
▼
Print Monitoring (both workflows, or on user request)
Gate: Before ANY search/generate/download, you MUST complete this step.
Collect before proceeding:
Model requirements:
Print parameters:
Model source — ask user:
"Do you want me to:
- 🔎 Search online — existing models, usually higher quality
- 🎨 AI generate — custom model from scratch
- 🤷 Not sure — I'll search first, generate if nothing fits"
Default: search first. Common objects (phone stand, hook, vase) almost always exist online.
Decision flow: User says "search" / "generate" / "not sure" → If "not sure" → search first → if no good results → offer generate.
Auto-routing (agent determines path based on description):
| Signal in user's description | Route to | Examples |
|---|---|---|
| Specific dimensions / tolerances / fit | Parametric (Workflow F) | "M3 screw hole", "inner diameter 40mm", "press fit" |
| Standard interfaces / mounting | Parametric (Workflow F) | "USB-C cutout", "GoPro mount", "VESA mount" |
| Functional part keywords | Parametric (Workflow F) | "bracket", "hinge", "hook", "clip", "gear", "mount", "enclosure", "stand" |
| Characters / figurines / organic | AI Generate (Workflow B/C) | "pikachu", "dragon", "bust", "sculpture" |
| Decorative / artistic | AI Generate (Workflow B/C) | "vase", "lamp shade", "desk ornament" |
| Photo reference | Image-to-3D (Workflow E) | user sends image file or URL |
When the description clearly matches functional/precision signals, skip the source question and route directly to Workflow F. If ambiguous (e.g., "phone stand" — could be searched or parametric), default to search first.
Gate: Before this step, you MUST have asked user: "Search, generate, or not sure?" Default: search first.
search.py "query" --limit 5 → MakerWorld, Printables, Thingiverse, ThangsIf no good results → offer AI generate.
Checkpoint before generate: Did you ask for dimensions? If not, ask now.
generate.py textgenerate.py text "prompt" --wait --height <mm> → auto-enhances, auto-scales to exact targetpreview.py model.stl --views turntable --height <mm> -o preview.gif → send GIF to chat (verifies dimensions)Checkpoint before generate: Did you ask for dimensions? If not, ask now. Do NOT ask user to specify colors upfront — AI textures determine the colors. Colorize will auto-detect them.
Same disclaimer as B
Confirm dimensions only — "What size do you want?" is the only required question
generate.py text "prompt" --wait --height <mm> → textured GLB (scaled to target height)
python3 scripts/colorize model.glb --height <mm> --max_colors 8 --bambu-map → vertex-color OBJ + _color_map.txt
preview.py model.obj --views turntable --height <mm> -o preview.gif
Send ONE consolidated report (MUST include all of the following in a single message):
Multi-color report template:
🎨 [Model Name] Multi-Color Preview
📷 [attach _preview.png AND turntable.gif]
# Color Hex % Suggested Filament ΔE 1 yellow #FFD700 58% PLA Basic Yellow 3.2 2 brown #8B4513 22% PLA Basic Brown 5.1 ... N colors detected, AMS compatible. Ready to proceed?
- Want fewer colors → I'll re-run with
--max_colors N- Want to adjust → tell me what to change
- Looks good → I'll open in Bambu Studio
WAIT for user response. If user requests changes → re-run colorize → show updated report
When user approves → Model Processing
⚠️ BS import may fail to detect vertex colors — see Step 4 for import procedure.
Colorize tuning (only if user requests adjustments):
| Parameter | Default | Effect |
|---|---|---|
--max_colors N | 8 | Maximum colors (hard limit ≤8 for AMS) |
--min-pct X | 0.1 | Min family % threshold (0=keep all, 5=aggressive filter) |
--no-merge | off | Disable family group exclusion (all 12 families independent) |
--island-size N | 1000 | Remove isolated patches < N pixels (0=disabled) |
--smooth N | 5 | Majority vote boundary passes (0=raw, higher=smoother) |
--bambu-map | on | Output _color_map.txt with suggested Bambu filaments (CIELAB match) |
Trigger: User provides a photo, image file, or image URL to generate a 3D model from.
Checkpoint: Did you ask for dimensions? If not, ask now. Do NOT ask for colors — they come from the image.
python3 scripts/generate.py image photo.jpg --wait (auto: validate, remove background, enhance prompt)
--no-bg-remove--rawTips for best results:
--no-bg-removeTrigger: User requests a part with precise dimensions, standard interfaces (screw holes, mounts), or functional keywords (bracket, hinge, enclosure). See auto-routing table in Step 1.
Checkpoint: MUST have exact dimensions in mm. Do NOT accept vague sizes like "about 80mm" — ask for precise values.
parametric.py command:
box, cylinder, sphere, extrudebracket --width W --height H --thickness T --hole-diameter Dplate-with-holes --width W --depth D --holes N --hole-diameter D --hole-spacing Senclosure --width W --depth D --height H --wall T [--lid]csg spec.jsonpython3 scripts/parametric.py <command> [args] -o model.stlpreview.py model.stl --views turntable -o preview.gif → send GIF to chatAdvantages over AI generation:
Limitations:
Reference: See references/manifold-examples.md for tolerance tables, CSG JSON patterns, and design rules.
Gate: Before this step, you MUST have a model file (from search, generate, or user).
All models MUST go through this. No exceptions. NEVER skip analyze or preview.
Analysis (11-point check):
analyze.py model.stl --orient --repair --material PLA --purpose functional
Checks: dimensional tolerance, wall thickness, load direction, overhangs (>45°), print orientation, floating parts, layer height, infill rate, wall count, top layers, material compatibility. Also: watertight, manifold, build volume fit.
Auto-repair: Fix normals, fill holes, remove degenerate faces.
Auto-orient: Optimal stability, auto unit detection (meters→mm).
Report to user (MANDATORY):
Example: "Score 8/10. Repaired 58K non-manifold edges. Walls: 1.5mm ✅ Overhangs: 3.2% ✅ Recommended: 0.20mm layers, 20% infill, PLA 210°C."
Preview rendering (MANDATORY — NEVER skip):
preview.py model.stl --views turntable -o model_preview.gif
--views perspective for a single imageOptional CLI Slice (only if user explicitly requests):
slice.py model.stl --orient --arrange --quality standard
Auto-detects printer + nozzle. Quality: draft(0.24) / standard(0.20) / fine(0.12) / extra(0.08). Output: .3mf with G-code.
⛔ MANDATORY — NEVER SKIP
Gate: Before this step, you MUST have: (1) sent preview to chat.
open -a "BambuStudio" model.3mf (or .stl/.obj)"I've opened the model in Bambu Studio. Please:
- Check: does it look correct? Missing or deformed parts?
- Check: floating/disconnected pieces?
- Check: correct size? (check dimensions in bottom bar)
- For multi-color: verify the right panel shows the correct number of colors
- Slice in Bambu Studio (Ctrl+R / Cmd+R) and review: estimated time, filament usage, supports. Let me know when ready!"
⛔ NEVER auto-print. AI models frequently have errors analysis can't fully catch.
⚠️ Requires Developer Mode ON. Bambu Studio and Bambu Handy will disconnect.
bambu.py print model.3mf --confirmedPrint detection — two methods:
Active listen (after model handoff): When agent opens a model in BS (Workflow B/C/D), immediately start a background MQTT listener (30 min window). If printer state changes to RUNNING → notify user and offer monitoring.
exec running paho-mqtt subscribe loop, poll every 30s for state changeHeartbeat fallback: During regular heartbeats, check printer MQTT status. If RUNNING and not already monitoring → notify user.
Trigger: Auto print (Workflow E), manual print (Workflow F), or user request. Requires LAN mode.
⚠️ Always ask: "Want me to monitor? Auto-pause on serious issues?"
Monitoring method: Direct MQTT subscription via paho-mqtt (NOT bambulabs_api — it has SSL issues).
Connect to {printer_ip}:8883, subscribe to device/{serial}/report, parse print messages.
Camera snapshots are MANDATORY during monitoring:
bambu.py snapshot (ffmpeg → rtsps://bblp:{code}@{ip}:322/streaming/live/1)Default monitoring schedule (milestone-based, ~5 messages per print):
| Event | Trigger | Action |
|---|---|---|
| Print start | State → RUNNING | Notify + 📸 snapshot |
| 25% progress | mc_percent ≥ 25 | Status + 📸 snapshot |
| 50% progress | mc_percent ≥ 50 | Status + 📸 snapshot |
| 75% progress | mc_percent ≥ 75 | Status + 📸 snapshot |
| Print complete | State → FINISH/IDLE | Completion + 📸 final snapshot |
| Anomaly | Any time | Immediate alert + 📸 snapshot + auto-pause (if enabled) |
User can adjust frequency. Track reported milestones to avoid duplicates.
Anomaly detection:
| Anomaly | Severity | Action |
|---|---|---|
| Progress stall >10min | Warning | Alert user + snapshot |
| Temperature anomaly | Critical | Alert + snapshot + auto-pause |
| Print failure/error | Critical | Alert + snapshot + auto-pause |
| Unexpected pause | Warning | Alert user + snapshot |
| Bed detachment | Critical | Auto-pause + alert + snapshot |
| Spaghetti | Critical | Auto-pause + alert + snapshot |
Status report format (send to user):
🖨️ Print Update — {filename}
📊 Progress: {percent}% | Layer {current}/{total}
⏱️ Remaining: {time}
🔥 Nozzle: {temp}°C | 🛏️ Bed: {temp}°C
📸 [attached snapshot]
Triggered when config.json doesn't exist. Conversational:
print_mode: "manual" or print_mode: "auto" in config.jsonconfig.json + .secrets.json (chmod 600, git-ignored)Required: python3, pip3 (macOS recommended; core scripts work cross-platform)
pip3 install bambulabs-api bambu-lab-cloud-api requests trimesh numpy Pillow ddgs pygltflib cryptography paho-mqtt scipy
Optional (macOS): ffmpeg (camera), Bambu Studio (model preview + slicing), Blender 4.0+ (multi-color + HQ preview), OrcaSlicer (CLI slicing)
Env vars (override config.json): BAMBU_MODE, BAMBU_MODEL, BAMBU_EMAIL, BAMBU_IP, BAMBU_SERIAL, BAMBU_3D_PROVIDER
Secrets (.secrets.json, chmod 600): password, access_code, 3d_api_key. All user-provided, never shipped.
| Mistake | Correct behavior |
|---|---|
| Skipping "search vs generate" question | MUST ask user first. Default: search. |
| Generating without dimensions | MUST ask "How big? e.g., 80mm tall" |
| Running generate.py then immediately opening BS | MUST run analyze.py and preview.py in between |
| Saying "I've prepared the model" without sending image | MUST attach preview GIF/image to the message |
| Opening Bambu Studio without user seeing preview | User must see preview in chat BEFORE you open BS |
| Proceeding to print without "looks good" | MUST wait for explicit user confirmation |
| Skipping analyze "because it's from search" | ALL models need analyze — search results can have issues too |
| Re-generating when model has 68 fragments | First check preview — AI meshes often report many "bodies" but look fine. Only use --keep-main if model is visually fragmented |
| Problem | Fix |
|---|---|
| SSL handshake error (LAN) | Normal (self-signed certs). Handled automatically. |
| API method not found | pip3 install --upgrade bambulabs-api (v2.6.6+) |
| Can't connect (LAN) | LAN Mode ON + correct IP + same network |
| Cloud verification code | Wait for email, enter once. Token cached 90 days. |
| Camera timeout | Wake printer (tap screen), check IP. |
| AI model has holes/floating parts | Expected. Always run analyze.py --repair. |
| Tripo/ Meshy reports 68+ "bodies" | Usually harmless (non-manifold topology, not actual fragments). Check preview first — only use --keep-main if model is visually broken |
| BS imports multi-color OBJ as single color | Close BS → reopen → File > New Project > Import OBJ (not "Import to plate"). If still single-color after retry, this is a BS-side compatibility issue — do NOT re-run colorize |
| Feature | Status |
|---|---|
| Single-color pipeline | ✅ Stable |
| Multi-color (colorize) | ⚠️ Colorize pipeline stable; BS vertex-color OBJ import occasionally fails to detect colors — use File → New Project → Import, NOT "Import to plate" |
| CLI slicing | ✅ OrcaSlicer backend (BS CLI SEGFAULT in v2.5.0) |
| End-to-end auto-print | ✅ Works with Developer Mode ON (X.509 signed MQTT + FTP upload) |
| Parametric modeling | ✅ manifold3d — geometric/functional parts only, no organic forms. Single-color STL output. |
references/model-specs.md — All 9 printer specificationsreferences/manifold-examples.md — Parametric modeling API, tolerance tables, CSG patternsreferences/bambu_filament_colors.json — Bambu Lab 43-color palette (reference only, colorize v4 uses texture-native colors)references/bambu-mqtt-protocol.md — MQTT protocolreferences/bambu-cloud-api.md — Cloud APIreferences/3d-generation-apis.md — Provider API endpointsreferences/3d-prompt-guide.md — Prompt engineering for 3DMIT · GitHub: https://github.com/heyixuan2/bambu-studio-ai