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 \x3Ctext|image> \x3Ccommand> [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:

\x3CEntityType[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] \x3Cscan|hide|restore> [options]

Namespace options:

Input methods:

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:

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:

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 "\x3Cperson 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:

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 \x3Cmapping-dir>/\x3Cfilename>.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 \x3CEntityType[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 \x3Cperson name[1]> is the same person; \x3Cperson 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] \x3Cscan|hide|categories> [options]

Namespace options:

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:

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:

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 \x3Cdir> for plaintext
2. run has image scan --dir \x3Cdir> 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.