Sticker Manager

Manage a local sticker / reaction-image library with keyword lookup, quality checks, semantic tags, batch import/collection workflows, and media sending support.

Authors:

• Wenzhuang Zhu
• TetraClaw (丁蟹)

Repository / backup source:

• GitHub: https://github.com/TetraClaw/sticker-manager
• If ClawHub is unavailable, use GitHub as the fallback download source.

What this skill does

1. Save the latest inbound image or GIF into a local library
2. Save a specific image from recent chat/media history
3. Search stickers by keyword
4. Rename or delete existing stickers
5. Clean very low-quality files
6. Tag stickers with emotions / scenes / keywords / descriptions
7. Recommend a sticker based on direct text context or recent chat history
8. Batch-collect stickers toward a target count with dedupe and low-quality filtering
9. Batch-import stickers from local directories
10. Prepare vision-model plans for semantic tagging and image understanding
11. Return resolved file paths so the assistant can send matched media with the message tool

Supported formats

• JPG
• JPEG
• PNG
• WEBP
• GIF

Default paths

• Sticker library: ~/.openclaw/workspace/stickers/library/
• Inbound media: ~/.openclaw/media/inbound/

Environment overrides:

• STICKER_MANAGER_DIR
• STICKER_MANAGER_INBOUND_DIR
• STICKER_MANAGER_LANG
• STICKER_MANAGER_VISION_MODELS

Typical use cases

1. Save a sticker

When the user sends an image/GIF and says things like:

• "save sticker"
• "store this"
• "save this image"
• "save the previous image"
• "save that image from chat history"

Basic save:

python3 scripts/save_sticker.py "custom_name"

Save from recent media history:

python3 scripts/save_sticker.py --list-history
python3 scripts/save_sticker.py --history-index=2 "saved_from_history"
python3 scripts/save_sticker.py --source=file_39---example.jpg "saved_by_source"

Quality-aware save:

python3 scripts/save_sticker_auto.py "custom_name"
python3 scripts/save_sticker_auto.py --history-index=3 "quality_checked_name"

If no name is provided, save_sticker_auto.py exits with code 2 and returns analysis markers so the assistant can ask a model to name the image.

2. Search a sticker

Command:

python3 scripts/get_sticker.py "keyword"

List all stickers:

python3 scripts/get_sticker.py

Matching order:

• exact filename match
• partial filename match
• fuzzy containment match

3. Rename / delete / clean

Rename:

python3 scripts/manage_sticker.py rename "old_name" "new_name"

Delete:

python3 scripts/manage_sticker.py delete "name"

Clean very small files:

python3 scripts/manage_sticker.py clean

4. Tag and recommend

Add tags:

python3 scripts/sticker_semantic.py tag "sticker_name" "happy,calm" "meeting,celebration" "thumbs-up,approved" "A calm approval reaction image."

Suggest for direct context:

python3 scripts/sticker_semantic.py suggest "we finally fixed it"
python3 scripts/sticker_semantic.py suggest "we finally fixed it" --strategy=model

List tag database:

python3 scripts/sticker_semantic.py list

Prepare model payload only:

python3 scripts/sticker_semantic.py prepare-model "the user is nervous but pretending to be calm"

Recommend from chat history:

python3 scripts/sticker_semantic.py context-recommend ./chat_history.json --top=5

5. Batch collect / import / discover

Collect from URLs or local files:

python3 scripts/collect_stickers.py --sources-file ./sources.txt --out-dir ./stickers/batch --prefix sticker --target-count 15

If the final count is below target, the command exits with code 2 and prints NEED_MORE=....

Import from local directories:

python3 scripts/batch_import.py ./stickers --target-dir ~/.openclaw/workspace/stickers/library/
python3 scripts/batch_import.py ./stickers --auto-tag

Discover sources from directories, URLs, or pages:

python3 scripts/discover_sources.py ./stickers
python3 scripts/discover_sources.py https://example.com/image1.gif
python3 scripts/discover_sources.py https://example.com/gallery
python3 scripts/discover_sources.py --fetch-urls https://example.com/image1.gif

Default discovery is lightweight:

• local directories are scanned immediately
• remote image URLs are returned as pending unless --fetch-urls is used
• page discovery only counts successfully extracted image URLs

Animation rule (mandatory):

• If the source is originally animated, prefer downloading the animated asset itself.
• Use a generic decision path: file suffix → HTTP Content-Type → downloaded file content validation.
• Do not silently downgrade animated sources to static WEBP/PNG previews.
• If a source looks animated by reference/content-type but the downloaded file validates as static, reject it from the animated batch instead of pretending it is a GIF.
• Before sending or importing a GIF batch, verify the saved file is actually animated-capable rather than a static preview.

6. Auto-tagging and vision planning

Generate a vision plan for a single file:

python3 scripts/sticker_semantic.py auto-tag ./sticker.gif

Generate plans for a directory:

python3 scripts/sticker_semantic.py auto-tag-dir ./stickers/

Standalone vision fallback plan:

python3 scripts/sticker_semantic.py vision-plan ./sample.png "find a doubtful or suspicious emotion"

This returns a JSON plan with:

• image path
• candidate vision models
• prompt goal
• fallback failure message

Suggested default model order:

1. bailian/kimi-k2.5
2. openai/gpt-5-mini

Sending workflow

After resolving a file path, send it with the message tool.

Example:

message(
    action="send",
    channel="telegram",
    target="<chat_id>",
    media="/absolute/path/to/sticker.gif",
    caption="Here you go"
)

If you need to reply to a specific message, pass replyTo="".

Quality rules

The auto-save flow checks media size before saving.

Force-save example:

python3 scripts/save_sticker_auto.py "low_quality_name" --force

Notes for agents

• Prefer semantic names over timestamp-heavy names
• Avoid platform-specific hardcoding in skill logic
• Use environment variables for library location overrides
• Keep send logic in the assistant/tool layer, not inside raw scripts when possible
• Validate file existence before sending
• For image meaning extraction, try the configured vision-capable model chain in STICKER_MANAGER_VISION_MODELS
• If the primary image model fails, try fallback models before giving up
• If all vision models fail, explicitly tell the user that image meaning, semantic tagging, and quality validation could not be completed reliably
• Treat __MODEL_MATCH__, __AUTO_TAG__, __SEMANTIC_BATCH__, __ANALYZE_HISTORY__, and __CONTEXT_RECOMMEND__ markers as structured handoff payloads for the outer assistant layer

Files

• scripts/common.py - shared path, i18n, and vision-plan helpers
• scripts/get_sticker.py - keyword lookup and inventory list
• scripts/manage_sticker.py - rename, delete, and cleanup
• scripts/save_sticker.py - basic save from inbound or history media
• scripts/save_sticker_auto.py - quality-aware save flow
• scripts/sticker_semantic.py - tagging, recommendation, auto-tag planning, and context analysis
• scripts/collect_stickers.py - batch collection with dedupe and semantic-plan output
• scripts/batch_import.py - local-directory import with optional auto-tag planning
• scripts/discover_sources.py - discovery from URLs, directories, and static pages
• scripts/check_sensitive.py - publish-safety scan for sensitive-looking content
• tests/ - pytest coverage for CLI and workflow behaviors