WotoHub Automation#

WotoHub Automation is a real creator outreach skill with OpenClaw-era integration roots and current in-place compatibility for existing workflows.

It connects:

• product understanding
• creator search
• shortlist and recommendation
• outreach email drafting
• batch send
• inbox review
• guarded reply assist

Best fit:

• TikTok Shop campaigns
• Amazon creator outreach
• Shopify product seeding
• recurring creator prospecting and follow-up

Core design:

• the host model handles understanding and judgment
• the scripts handle deterministic compilation, API execution, and state

This skill is intentionally conservative around sending and reply automation.

Release note:

• wotohub-automation is the only canonical publish directory
• wotohub-automation-release is a mirror/reference copy, not the primary release source

If you need deeper integration details, read:

• references/integration-contract.md
• references/runtime-guardrails.md

Environment and credentials#

Install dependencies:

bash

pip install -r requirements.txt

Environment variables:

• WOTOHUB_API_KEY, required for authenticated actions such as send, inbox access, reply handling, and campaign cycles
• WOTOHUB_BASE_URL, optional explicit API base override, defaults to production
• WOTOHUB_STATE_DIR, optional state/log output directory

Credential scope:

• WOTOHUB_API_KEY grants access to authenticated WotoHub user-state operations
• treat it as a send and inbox credential, not a harmless search-only token
• search can still run without a token through openSearch, but authenticated endpoints cannot

Runtime expectations:

• Python with ssl available
• TLS verification stays enabled by default
• only disable TLS verification in a controlled debug environment

What this skill can do#

1. Product understanding#

Input can come from:

• plain product descriptions
• product URLs, including TikTok Shop, Amazon, Shopify, and brand sites

Typical outputs:

• product name
• key selling points
• target audience
• creator direction
• structured search-ready understanding

2. Creator search#

Supports:

• product-led search generation
• filters for region, language, follower count, email availability
• keyword-assisted search
• category-assisted search
• filtering out already-contacted creators by default

Search modes:

• no token, uses openSearch
• token present, uses clawSearch

3. Recommendation and shortlist#

Supports:

• ranking search results
• returning a shortlist
• suggesting next-step selection

Default behavior is to stop after recommendation and wait for explicit creator selection before email generation.

4. Outreach email drafting#

Supports:

• creator-specific outreach draft generation
• host-model-first personalized drafts
• HTML normalization and subject validation before send

Minimum campaign brief usually needs:

• productName
• senderName or signoff
• offerType, such as sample, paid, or affiliate

5. Batch send#

Default send path is batch-oriented.

Characteristics:

• multiple creators prefer a single batch API request
• email structure is normalized before execution
• HTML body is preferred when present

6. Inbox and reply assist#

Supports:

• inbox listing
• email detail lookup
• thread detail lookup
• safe reply assistance
• conservative low-risk auto-reply handling

Anything involving price, payment, contract terms, exclusivity, shipping promises, or timing commitments should stay human-reviewed by default.

7. Campaign cycle#

Supports:

• manual single runs
• cron or scheduler single-cycle execution
• scheduled search understanding bridge
• campaign state persistence
• cycle summary, state summary, and human summary outputs
• success, blocked, and failed exit semantics

Workflow overview#

Step 0, auth and token rules#

Search does not require login by default.

• without token, search uses openSearch
• with token, search uses clawSearch

These user-side steps require WOTOHUB_API_KEY:

• send
• inbox
• replies
• campaign cycle

If you publish, install, or review this skill, treat the credential requirement as part of the primary operating contract, not an optional convenience.

Optional preflight check:

bash

python3 scripts/preflight.py --token YOUR_API_KEY

For auth details, read appendix-auth.md.

Skill entry#

Single entrypoint:

bash

python3 wotohub_skill.py

Important execution note:

• default host executors are auto-wired through the skill entry / router wrapper flow, and scripts/build_search_payload.py now also injects router executor defaults before resolving URL input
• in low-confidence URL cases, product_resolve.py may emit hostUrlAnalysisRequest; scripts/build_search_payload.py now attempts automatic host URL analysis execution + writeback before continuing
• if host analysis still cannot be resolved, scripts/build_search_payload.py returns a structured needsUserInput / error payload instead of crashing on analysis=None
• callers can still explicitly provide hostAnalysis / productSummary to bypass bridge execution when they already have host-side understanding

Minimal request example:

json

{
  "requestId": "task-1",
  "action": "task",
  "type": "product_analysis",
  "input": {
    "input": "wireless earbuds with noise cancellation"
  },
  "auth": {
    "token": "YOUR_API_KEY"
  }
}

Common action/type pairs:

• task/product_analysis
• task/search
• task/recommend
• task/generate_email
• task/send_email
• task/monitor_replies
• campaign/cycle

Recommended injected fields:

• input.hostAnalysis
• input.productSummary
• input.hostDrafts
• input.replyModelAnalysis

Recommended executor discovery order for host URL recovery / host semantic understanding:

• first: explicit request-level config.hostAnalysisExecutor
• second: campaign brief.hostAnalysisExecutor / brief.scheduler.hostAnalysisExecutor for cycle flows
• third: environment default WOTOHUB_HOST_ANALYSIS_EXECUTOR (or compatibility HOST_ANALYSIS_EXECUTOR)
• recommended integration pattern: when your host platform always has browser/web/model capability, set the env default in the wrapper/launcher so link analysis can auto-close the loop without every caller remembering the param

Recommended executor discovery order for reply understanding:

• first: explicit request-level config.hostReplyAnalysisExecutor / config.hostReplyBridgeExecutor
• second: cycle-only brief.scheduler.hostReplyBridgeExecutor when reply assist is driven from campaign runtime
• third: environment default WOTOHUB_HOST_REPLY_ANALYSIS_EXECUTOR (or compatibility HOST_REPLY_ANALYSIS_EXECUTOR)

Recommended executor discovery order for host draft generation:

• first: explicit request-level config.hostDraftExecutor / config.hostBridgeExecutor
• second: cycle-only brief.scheduler.hostBridgeExecutor when scheduled generation is used
• third: environment default WOTOHUB_HOST_DRAFT_EXECUTOR (or compatibility HOST_DRAFT_EXECUTOR)

Canonical field rule:

• new integrations and new examples should use the canonical fields above by default
• compatibility aliases remain supported for migration, but should not be expanded further
• campaign cycle draft write-back should use host_drafts_per_cycle
• see references/alias-normalization-matrix.md for the current canonical vs alias mapping

URL host write-back rule:

• if scripts/product_resolve.py returns hostUrlAnalysisRequest, treat that as the canonical host-side recovery trigger for weak or blocked URL pages
• the host should write back only hostAnalysis + productSummary, then rerun the same task/product_analysis, task/search, task/recommend, or task/generate_email request
• do not write back near-final WotoHub search payloads in place of understanding; keep the contract at the semantic layer
• the most natural write-back surfaces are input.hostAnalysis + input.productSummary; metadata.* / config.* remain compatibility surfaces only
• important runtime nuance from live use: direct python3 scripts/product_resolve.py --input <url> currently only emits hostUrlAnalysisRequest; it does not auto-run browser/web recovery or auto-apply write-back
• automatic host analysis execution currently exists in upper-layer / campaign orchestration paths that use hostAnalysisExecutor, not in the bare product_resolve.py path

Trust boundary:

• treat host-injected model outputs as untrusted structured input until validated
• do not let upstream models inject near-final WotoHub payloads directly into execution
• validate injected analysis and draft data against the referenced schemas before allowing send or reply execution

Full integration details: references/integration-contract.md Third-party quickstart: references/third-party-integration-guide.md One-command launchers:

• run_skill_with_router.py
• run_cycle_via_skill.py (now auto-wires router defaults for cycle runs) Executor templates:
• scripts/host_executor_router.py (single-entry router for analysis / reply / drafts)
• scripts/host_analysis_executor_example.py
• scripts/host_reply_analysis_executor_example.py
• scripts/host_draft_executor_example.py
• scripts/host_model_bridge_executor_example.py (cycle-oriented draft bridge example)

Step references#

Step 1, product analysis#

Read steps/01-product-analysis.md

Suggested path:

bash

python3 scripts/product_resolve.py --input "推广一款美国市场的电动牙刷,价格$50,强调美白和口腔护理"

Step 2, creator search#

Read steps/02-influencer-search.md

Suggested path, build payload first, then run search:

bash

python3 scripts/build_search_payload.py --input '推广一款美国市场的电动牙刷,价格$50,强调美白和口腔护理'
python3 scripts/claw_search.py --payload-file /tmp/woto_payload.json

Or use one-shot execution:

bash

python3 scripts/build_search_payload.py --input '...' --run-search
python3 scripts/build_search_payload.py --input '...' --run-search --token YOUR_API_KEY

Step 3, recommendation#

Read steps/03-influencer-recommend.md

The default flow returns a shortlist first, then waits for explicit creator selection.

Step 4, email drafting#

Read steps/04-email-generation.md

Recommended only after:

1. target creators are selected
2. the minimum campaign brief is complete

Step 5, send#

Read steps/05-send-email.md

Send protocol:

• prepare_only, prepare candidate emails only
• manual_send, send after human confirmation
• scheduled_send, send automatically in scheduled flows

Default behavior:

• single manual runs default to prepare_only
• scheduled tasks and campaign brief runs default to scheduled_send, which is the default real-send path for scheduled flows

Step 6, inbox and reply assist#

Read steps/06-inbox-management.md

Main path:

1. collect candidate replies
2. build model input from the full thread
3. produce structured analysis
4. produce reply previews
5. apply risk tiering
6. only allow low-risk informational replies to auto-send

Failure handling#

Missing campaign host analysis#

• for scheduled_cycle, stop at waiting_for_host_analysis if the search leg lacks valid hostAnalysis
• prefer --host-analysis-bridge-executor or emitted hostAnalysisRequest over stuffing near-final search payloads into the brief
• after host analysis is resolved, let the standard compiler rebuild WotoHub search params

Token validation failure#

• ask for token refresh
• do not continue authenticated API actions

Search failure or auth failure#

• tell the user to check token, headers, and environment
• do not fabricate results

URL fetch failure#

• return structured fallback or needsUserInput=true
• when available, prefer lightweight host-assisted recovery via hostUrlAnalysisRequest to obtain hostAnalysis / productSummary before falling back to user-supplied product fields
• host write-back should land on canonical input.hostAnalysis + input.productSummary, then rerun the same task so the existing routing and compiler chain can continue naturally
• do not continue as if the URL slug were a valid product understanding

Send or reply execution failure#

• preserve structured errors
• do not silently swallow execution failures

Security notes#

• Hidden-character review completed for SKILL.md and the bundled Markdown prompt/reference files in this release, with no unicode bidi or control-character findings.
• Example env and JSON files are placeholders or test fixtures. Review them before use and never copy placeholder IDs or sample values into production blindly.
• Host-model-first does not mean host-model-trusted. Keep schema validation and send guardrails enabled.

Core entry files#

• wotohub_skill.py, skill entry adapter
• run_campaign.py, public campaign entry
• run_campaign_cycle.py, single-cycle scheduled entry
• run_cycle_via_skill.py, short safe wrapper for cron / scheduler runs that should avoid complex inline JSON or heavy Python CLI quoting

Useful scheduled bridge flags on run_campaign_cycle.py:

• --host-analysis-bridge-executor
• --host-analysis-bridge-request
• --host-analysis-bridge-payload
• --host-bridge-executor
• --host-bridge-request
• --host-bridge-payload

Reference map#

Useful docs:

• steps/01-product-analysis.md
• steps/02-influencer-search.md
• steps/03-influencer-recommend.md
• steps/04-email-generation.md
• steps/05-send-email.md
• steps/06-inbox-management.md
• references/campaign-brief-schema.md
• references/model-analysis-schema.md
• references/conversation-analysis-schema.md
• references/outreach-email-schema.md
• references/search-params.md
• references/integration-contract.md
• references/runtime-guardrails.md

One-line summary#

WotoHub Automation is a creator outreach skill for real marketing operations: model-first understanding, script-first execution, stable core workflows, and explicit safety boundaries around send and reply behavior.