EZCTO Smart Web Reader for OpenClaw

What it does

Reads any URL and returns structured JSON containing page identity, content sections, image descriptions (text-inferred), video metadata, and actionable links. Acts as the Agent's default web access layer — replacing raw web_fetch with zero-token cache hits and intelligent HTML parsing. 80%+ token savings vs screenshots.

Key Features

✓ Transparent URL interception - Fires automatically whenever Agent accesses any URL
✓ Cache-first strategy - Check EZCTO asset library before parsing (zero cost)
✓ Zero-token site detection - Auto-detect crypto/ecommerce/restaurant sites via text matching
✓ Local-first storage - Aligns with OpenClaw's philosophy (~/.ezcto/cache/)
✓ Community-driven - Contribute parsed results back to shared asset library
✓ OpenClaw-native output - Includes agent suggestions and skill chaining hints

---

Security Manifest

Category	Detail
External endpoints	INLINECODE1 only (EZCTO community cache)
Data transmitted

URL string, SHA256 HTML hash, extracted structured JSON |
| NOT transmitted | Raw HTML, local file contents, credentials, env variables |
| Shell injection guard | All user-supplied values URL-encoded or passed as python3 args, never string-interpolated |
| Prompt injection guard | HTML sanitized (scripts/styles/comments stripped), wrapped in <untrusted_html_content> XML delimiters, explicit LLM guardrail injected before content |
| Shell commands used | curl (fetch/API), sha256sum (hashing), python3 (URL encoding, safe JSON construction) |
| Filesystem writes | ~/.ezcto/cache/ (cached results), /tmp/ (temp files, cleaned up) |

---

Workflow

Step 1: Check EZCTO Cache (Zero-cost fast path)

CODEBLOCK0

Conditional logic:

• - If http_code == 200 AND valid JSON → SKIP to Step 9 (return cached result)
• If http_code == 404 → Cache miss, continue to Step 2
• If http_code >= 500 → API error, log warning, continue to Step 2 (fallback mode)

OpenClaw note: Cache hits cost 0 tokens and complete in ~1 second.

---

Step 2: Fetch HTML

CODEBLOCK1

Error handling:
CODEBLOCK2

Guardrail: If HTML > 500KB, extract <body> only to prevent context overflow.

---

Step 3: Compute HTML Hash (Tamper-proof verification)

CODEBLOCK3

Purpose: Enables deduplication and tamper detection in the asset library.

---

Step 4: Auto-detect Site Type (Zero tokens, pure text matching)

Execute pattern matching per references/site-type-detection.md:

CODEBLOCK4

---

Step 5: Assemble Translation Prompt

CODEBLOCK5

Token optimization: If HTML + prompt > 100K tokens, truncate HTML to first 50KB + last 10KB (preserves header and footer).

---

Step 6: Parse HTML with Local LLM

CODEBLOCK6

Error handling:

if (!result.content || result.content.length < 50) {
  return {
    "status": "error",
    "error": {
      "code": "translation_failed",
      "message": "LLM returned empty or invalid response",
      "suggestion": "Try again or check if HTML is too malformed"
    }
  }
}

---

Step 7: Validate JSON Output

CODEBLOCK8

---

Step 8: Dual-store (Local cache + Asset library)

8.1 Store locally (OpenClaw-native format)

CODEBLOCK9

8.2 Contribute to EZCTO asset library

CODEBLOCK10

---

Step 9: Return to OpenClaw Agent

Output format (OpenClaw-native wrapper):

CODEBLOCK11

For cache hits (Step 1 direct return):

{
  "skill": "ezcto-smart-web-reader",
  "status": "success",
  "result": { /* cached translation */ },
  "metadata": {
    "source": "cache",
    "cache_key": "ezcto_asset_library",
    "translation_time_ms": 234,
    "token_cost": 0,
    "cached_at": "2026-02-15T08:00:00Z"
  }
}

---

Guardrails

• - Never modify URLs - Preserve all URLs exactly as they appear in HTML
• Never fabricate data - Use null for missing fields, never guess
• Truncate large HTML - If HTML > 500KB, extract <body> only
• Report errors explicitly - Never silently fail, always return structured error
• Respect rate limits - If EZCTO API returns 429, back off for 60 seconds
• No sensitive data - Never store or transmit API keys, passwords, or PII

---

Dependencies

Reference files (must exist in same directory):

• - references/translate-prompt.md - Base translation instructions
• INLINECODE16 - JSON output specification
• INLINECODE17 - Site type detection rules
• INLINECODE18 - Crypto-specific extraction
• INLINECODE19 - E-commerce extraction
• INLINECODE20 - Restaurant extraction
• INLINECODE21 - OpenClaw integration guide

System requirements:

• - curl command available
• INLINECODE23 (or shasum -a 256 on macOS)
• Writable ~/.ezcto/cache/ directory

---

Testing

Test with a crypto site:
CODEBLOCK13

Test with e-commerce:
CODEBLOCK14

Test cache hit:

/use ezcto-smart-web-reader https://ezcto.fun
# Run again immediately - should return cached result in <2 seconds

---

Learn More

• - EZCTO Website: https://ezcto.fun
• API Documentation: https://ezcto.fun/api-docs
• OpenClaw Integration: See INLINECODE26
• Report Issues: https://github.com/pearl799/ezcto-web-translator/issues