has-anonymizer

name	has-anonymizer
description	HaS (Hide and Seek) on-device text and image anonymization. Text: 8 languages (zh/en/fr/de/es/pt/ja/ko), open-set entity types. Image: 21 privacy categories (face, fingerprint, ID card, passport, license plate, etc.). Use when: (1) anonymizing text before sending to cloud LLMs then restoring the response, (2) anonymizing documents, code, emails, or messages before sharing, (3) scanning text or images for sensitive content, (4) anonymizing logs before handing to ops/support, (5) masking faces/IDs/plates in photos before publishing or sharing.
metadata	{"openclaw":{"emoji":"🔒","requires":{"bins":["llama-server","uv"],"env":{"HAS_TEXT_MODEL_PATH":{"description":"Absolute path to the HaS text GGUF model (default: ~/.openclaw/tools/has-anonymizer/models/has_text_model.gguf)","required":false},"HAS_IMAGE_MODEL":{"description":"Absolute path to the HaS image YOLO model (default: ~/.openclaw/tools/has-anonymizer/models/sensitive_seg_best.pt)","required":false},"HAS_TEXT_MAX_PARALLEL_REQUESTS":{"description":"Maximum parallel inference requests for scan/hide/restore batch operations (default: 4, max: 4)","required":false}}},"install":[{"id":"brew-uv","kind":"brew","os":["darwin"],"formula":"uv","bins":["uv"],"label":"Install uv (brew)"},{"id":"brew-llama","kind":"brew","os":["darwin"],"formula":"llama.cpp","bins":["llama-server"],"label":"Install llama.cpp (brew)"},{"id":"download-model","kind":"download","url":"https://huggingface.co/xuanwulab/HaS_Text_0209_0.6B_Q8/resolve/main/has_text_model.gguf","targetDir":"models","label":"Download HaS text model Q8 (639 MB)"},{"id":"download-image-model","kind":"download","url":"https://huggingface.co/xuanwulab/HaS_Image_0209_FP32/resolve/main/sensitive_seg_best.pt","targetDir":"models","label":"Download HaS image model FP32 (119 MB)"}]}}

HaS Privacy

HaS exposes a single umbrella CLI:

• has text ... for text anonymization, restoration, and scanning
• has image ... for image scanning, masking, and category discovery

Use it when you need to remove private data locally before sending content elsewhere, inspect a directory for privacy risks, or mask visual privacy targets in photos and screenshots.

Agent Decision Guidelines

• Prefer has text for plaintext and has image for raster images. For mixed directories, run both and combine the results into one report.
• For PDFs, Word documents, or scanned pages, extract text first and then use has text. For screenshots/photos where the goal is simply to hide visible carriers such as faces, screens, paper, labels, or QR codes, use has image. If the goal is to reason about the text content inside an image, run OCR first and then use has text.
• Do not overwrite or delete the original files. Text commands can restore later, image masking is irreversible.
• Proactively mention configurable knobs when the user intent is clear: has text uses repeated --type; has image uses repeated --type, plus --method and --strength.
• If the user intent is ambiguous, start with scan before hide.
• After batch scans, summarize text file count, image file count, findings by type/category, high-risk items, and the suggested next step.
• If timing matters to the user, add --timing and report the elapsed result in plain language afterward.
• For qr_code and barcode, the default mosaic strength is automatically raised based on the detection size to ensure the encoding is destroyed. The agent does not need to manually increase --strength for these categories. If a detection output includes effective_strength, report it to the user.

Shared CLI Contract

The current CLI contract is designed for agents first:

• Success returns compact JSON.
• Failure also returns compact JSON with error.code and error.message.
• Returned path fields are absolute.
  • This includes file, output, mapping_output, and skipped[].file.
• Invalid combinations fail fast instead of silently falling back.
• Directory mode is non-recursive. Only immediate children are processed.
• Batch results can include skipped and skipped_count.
  • Treat skipped entries as unprocessed files, not as clean files.

Shared command layout:

{baseDir}/scripts/has.sh <text|image> <command> [options]

Shared options can be placed before or after the subcommand.

---

Part 1: has text

has text is the plaintext namespace. It supports:

• scan
• hide
• restore

It runs entirely on-device and uses a local llama-server plus the HaS text model when model inference is required.

Core Text Concepts

Semantic tags

Anonymized text uses semantic tags such as:

<EntityType[ID].Category.Attribute>

This preserves structure better than a flat [REDACTED] token and is the reason restored downstream LLM output can remain usable.

Open-set types

Repeated --type flags are open-set. They are not limited to a fixed catalog. Natural language type names such as "person name", "address", "phone number", or "numeric values (transaction amounts)" are valid.

Public/private distinction

Type wording matters. For example, "personal location" is usually safer than "location" if you want to preserve public places but hide private addresses. Public/private person-name distinctions remain less stable and should not be trusted without verification.

Multilingual support

The text model supports Chinese, English, French, German, Spanish, Portuguese, Japanese, and Korean, including mixed-language text.

Type name language

Match the --type language to the source text language:

• Chinese text → use Chinese type names: --type "人名" --type "电话号码" --type "地址"
• Non-Chinese text (English, French, German, etc.) → use English type names: --type "person name" --type "phone number" --type "address"

Text Runtime Prerequisites

has text auto-starts a local llama-server when needed.

• Default model path: ~/.openclaw/tools/has-anonymizer/models/has_text_model.gguf
• Override model path: HAS_TEXT_MODEL_PATH=/abs/path/to/has_text_model.gguf
• Override parallel cap: HAS_TEXT_MAX_PARALLEL_REQUESTS
• If HuggingFace downloads fail, see Model Download Mirrors below.

Text Usage

{baseDir}/scripts/has.sh text [--timing] [--verbose] <scan|hide|restore> [options]

Namespace options:

Option	Description
--timing	Include elapsed_ms in the JSON output
--verbose	Emit runtime status and progress messages to stderr

Input methods:

Method	Description
--text '<text>'	Pass text directly
--file <path>	Read text from a file
--dir <path>	Process immediate plaintext files in a directory
stdin	For single-text mode when no --text, --file, or --dir is provided

Rules:

• --text, --file, and --dir are mutually exclusive.
• Empty --type values are rejected.
• Directory mode only accepts batch output flags.
• Single-file hide requires --mapping-output.
• Single-file restore requires --mapping.
• In text directory mode, skipped can include unprocessed files (binary, encoding, or read errors).

has text scan

Finds sensitive entities without replacing them.

{baseDir}/scripts/has.sh text scan --type "person name" --type "phone number" --file report.txt
{baseDir}/scripts/has.sh text scan --type "person name" --type "phone number" --dir ./reports/

Parameters:

Parameter	Required	Description
--type	yes	Entity type to scan for; repeat to add more
--text / --file / --dir	one input	Input source
--max-chunk-tokens		Max tokens per chunk, default 5000
--max-parallel-requests		Max scan chunks in parallel, default 4

Output:

• Single-text mode returns {"entities": ...}
• Directory mode returns {"results":[...],"count":N,"summary":{...}}
• Batch output may include skipped and skipped_count

has text hide

Replaces sensitive entities with semantic tags.

{baseDir}/scripts/has.sh text hide --type "person name" --type "address" --text "John lives in Brooklyn" --mapping-output ./mapping.json
{baseDir}/scripts/has.sh text hide --type "person name" --file note.txt --output ./note.anonymized.txt --mapping-output ./note.mapping.json
{baseDir}/scripts/has.sh text hide --type "person name" --dir ./docs/

Parameters:

Parameter	Required	Description
--type	yes	Entity type to anonymize; repeat to add more
--text / --file / --dir	one input	Input source
--mapping-output	single-file: yes	Output path for generated mapping JSON
--output	single-file	Output path for anonymized text
--mapping	single-file	Existing mapping JSON file for incremental anonymization
--output-dir	batch	Output directory for anonymized files (default: <dir>/.has/anonymized/)
--mapping-dir	batch	Output directory for per-file mapping JSON files (default: <output-dir>/mappings/)
--max-chunk-tokens		Max tokens per chunk, default 3000
--max-parallel-requests		Max files in parallel for --dir, default 4
--no-tool-pair		Disable diff-based pair extraction; always use Model-Pair (slower but more robust)

Behavior:

• Single-file mode never emits the mapping table inline.
• Single-file mode returns either:
  • {"text":"...","mapping_output":"/abs/path/to/map.json"}
  • {"output":"/abs/path/to/out.txt","mapping_output":"/abs/path/to/map.json"}
• Batch mode does not accept shared --mapping.
• Mapping files are sensitive assets. Protect them.

has text restore

Restores anonymized text using mapping JSON.

{baseDir}/scripts/has.sh text restore --mapping mapping.json --text "<person name[1].personal.name> lives in ..."
{baseDir}/scripts/has.sh text restore --mapping mapping.json --file anonymized.txt --output restored.txt
{baseDir}/scripts/has.sh text restore --dir ./.has/anonymized/ --output-dir ./.has/restored/

Parameters:

Parameter	Required	Description
--mapping	single-file: yes	Mapping JSON file path
--text / --file / --dir	one input	Input source
--output	single-file	Output path for restored text
--mapping-dir	batch	Per-file mapping directory (default: <dir>/mappings/)
--output-dir	batch	Output directory for restored files (default: sibling restored/ under .has/, or <dir>/.has/restored/)
--max-chunk-tokens		Max tokens per chunk when model restore is needed, default 3000
--max-parallel-requests		Max model-backed restore chunks in parallel

Behavior:

• Single-file mode returns inline text unless --output is provided.
• restore --dir uses per-file mapping JSON files. It does not accept a shared --mapping.
• restore --dir expects mapping files at <mapping-dir>/<filename>.mapping.json (matching the naming convention produced by hide --dir).

Typical Text Workflow

Anonymize text before sending it to a cloud LLM, then restore the answer:

1. hide to produce anonymized text plus mapping
2. send anonymized text to the cloud model with a tag-format explanation (see below)
3. restore the model response with the mapping

For multi-line text, prefer file-based intermediates over shell variables.

Prompting the cloud LLM with anonymized text

When forwarding anonymized text to a cloud LLM, the agent must prepend a brief explanation of the tag format so the model understands and preserves the tags. Include wording equivalent to the following (adjust language to match the conversation):

The text below has been anonymized. Sensitive entities are replaced by tags in the format <EntityType[ID].Category.Attribute>:

• EntityType — the kind of entity (matches the --type value, e.g. person name, address, phone number).
• [ID] — a numeric identifier. The same type + same ID always refers to the same real-world entity (e.g. every <person name[1]> is the same person; <person name[2]> is a different person).
• .Category.Attribute — additional semantic classification of the entity.

Rules:

1. Preserve every tag exactly as-is in your response — do not modify, translate, paraphrase, omit, or expand any tag.
2. When referring to an anonymized entity, reuse the original tag with the correct ID.
3. Do not attempt to guess the real values behind the tags.

Omitting this explanation may cause the cloud model to strip, rewrite, or misinterpret the tags, which will break the restore step.

Model Download Mirrors

If HuggingFace downloads fail, use these ModelScope mirrors:

• text model: https://modelscope.cn/models/TencentXuanwu/HaS_Text_0209_0.6B_Q8
• image model: https://modelscope.cn/models/TencentXuanwu/HaS_Image_0209_FP32

---

Part 2: has image

has image is the image namespace. It supports:

• scan
• hide
• categories

It loads the YOLO segmentation model directly and does not require llama-server.

Image Usage

{baseDir}/scripts/has.sh image [--timing] [--model MODEL] <scan|hide|categories> [options]

Namespace options:

Option	Applies to	Description
--timing	all image commands	Include elapsed_ms in the JSON output
--model PATH	scan, hide	Override the image model path

Image Privacy Categories

Common categories include biometric_face, id_card, passport, license_plate, qr_code, mobile_screen, and paper.

Use has image categories when you need the full catalog of 21 supported classes.

--type accepts:

• English names
• Chinese names
• numeric IDs
• unique partial matches such as face

Rules:

• Empty --type values are rejected.
• Ambiguous partial matches fail fast.
• Omit --type to scan or mask all supported categories.
• In image directory mode, skipped can include unprocessed files.

has image scan

Finds privacy regions without modifying the image.

{baseDir}/scripts/has.sh image scan --image photo.jpg --type face --type id_card
{baseDir}/scripts/has.sh image scan --dir ./photos/ --type face

Parameters:

Parameter	Required	Description
--image / --dir	one input	Single image or batch directory
--type		Category filter; repeat to add more
--conf		Confidence threshold, default 0.25
--model		Override image model path

Output:

• Single-image mode returns detections and summary
• Directory mode returns results, count, summary, and optional skipped

has image hide

Detects and masks privacy regions in images.

{baseDir}/scripts/has.sh image hide --image photo.jpg --type face --method blur --strength 25
{baseDir}/scripts/has.sh image hide --dir ./photos/

Parameters:

Parameter	Required	Description
--image / --dir	one input	Single image or batch directory
--output	single-image	Output image path
--output-dir	batch	Output directory
--type		Category filter; repeat to add more
--method		mosaic, blur, or fill; default mosaic
--strength		Mosaic block size or blur radius; default 15
--fill-color		Fill color for fill; default #000000
--conf		Confidence threshold; default 0.25
--model		Override image model path

Behavior:

• Refuses to overwrite the source image.
• Directory mode accepts --output-dir, not --output.
• For qr_code and barcode detections with --method mosaic, the block size is automatically raised to max(strength, bbox_short_side // 10, 20) to prevent the encoding from surviving pixelation. After masking, a lightweight verification confirms the code is no longer machine-readable; if it is, the strength is escalated further (up to a fill fallback). Each affected detection includes an effective_strength field in the output.
• A cv2-based fallback supplements YOLO detection for QR codes and barcodes. When YOLO misses a code (e.g. large codes on plain backgrounds), cv2.QRCodeDetector and cv2.barcode.BarcodeDetector provide additional coverage. When YOLO misclassifies a code region as a different category (e.g. monitor_screen), cv2 corrects the category before --type filtering, so --type qr_code catches all QR codes regardless of YOLO's label. Corrected detections include a "corrected_from" field; new detections include "cv2_fallback": true.

has image categories

Lists all supported image privacy categories.

{baseDir}/scripts/has.sh image categories
{baseDir}/scripts/has.sh image categories --timing

Behavior:

• Returns {"categories":[...]}
• Supports --timing

Suggested Combined Scan

For a mixed workspace:

1. run has text scan ... --dir <dir> for plaintext
2. run has image scan --dir <dir> for images
3. merge the two JSON results into one privacy report

If the user wants masking after that, use hide on the specific files or directories you already identified.