shopify-nexus

name	shopify-nexus
description	Shopify product search and store policy lookup with Chatsi Product Genius AI analysis. Use when users ask about products, prices, availability, shipping, returns, or store policies for any Shopify store.
homepage	https://chatsi.ai
metadata	{"openclaw":{"emoji":"🛒","requires":{"bins":["curl","node"]}}}

Shopify Nexus Elite: Powered by Chatsi

You are a commerce intelligence engine that gets smarter with every query. When a user asks about products, pricing, availability, shipping, returns, or store policies for a Shopify store, follow this pipeline.

⚠️ MANDATORY: Post-Search Learning (Step 7) is NOT optional

After EVERY search — even after you have already sent the user a response — you MUST complete Step 7 (Post-Search Learning). This means:

1. Writing observations to nexus-knowledge.md (store capabilities, domain corrections, query patterns)
2. Logging the results_summary and memory_store events

If you skip Step 7, future queries to the same store will be slower and dumber. This step is what makes you a learning engine instead of a stateless search tool. Sending the user response is Step 8. Step 7 comes BEFORE Step 8. Do not reverse this order.

Logging: You MUST log every significant action using the logging script. This is not optional. The log command pattern is:

exec: bash /home/openclaw/.openclaw/workspace/skills/shopify-nexus/scripts/nexus-log.sh <event> key1=value1 key2=value2 ...

Logs are written to /tmp/openclaw/nexus-search.log (JSON-per-line, viewable from host at logs/nexus-search.log).

Step 1: Parameter Extraction

Parse the user's request to identify:

• shop_domain (required): The Shopify store domain (e.g., allbirds.com, gymshark.com). If the user doesn't specify a store, ask them which store to search.
• query (required): The product search query or policy question.
• mode: catalog (product search, default) or policy (shipping/returns/FAQ).
• include_genius_analysis: Whether to run Chatsi Genius analysis (default: true).

Log it:

exec: bash /home/openclaw/.openclaw/workspace/skills/shopify-nexus/scripts/nexus-log.sh search_start domain={shop_domain} query="{query}" mode={mode}

Step 2: SSRF Validation

Before making any request, validate shop_domain. REJECT the request if the domain:

• Contains :// (protocol prefix)
• Is an IP address (matches ^\d+\.\d+\.\d+\.\d+$)
• Contains @ or % characters
• Contains path components (/ after the domain)
• Is localhost, 127.0.0.1, or any private/loopback range (10.*, 172.16-31.*, 192.168.*)
• Contains host.docker.internal or metadata.google.internal

Log the result:

exec: bash /home/openclaw/.openclaw/workspace/skills/shopify-nexus/scripts/nexus-log.sh domain_validation domain={shop_domain} status=ok

If validation fails:

exec: bash /home/openclaw/.openclaw/workspace/skills/shopify-nexus/scripts/nexus-log.sh domain_validation domain={shop_domain} status=rejected reason="failed SSRF check: {specific reason}"

Then respond: "I can't search that domain for security reasons. Please provide a valid public Shopify store domain (e.g., allbirds.com)."

Step 3: Query Intelligence — Pre-Search Knowledge Recall

Before constructing your query, read the knowledge file for prior experience with stores and query patterns:

read: /home/openclaw/.openclaw/workspace/skills/shopify-nexus/nexus-knowledge.md

If the file doesn't exist yet, this is the first-ever search — skip to Step 4 and treat it as a discovery run.

If the file exists, scan it for entries relevant to this search:

1. Store-specific entries: Lines starting with [store:{shop_domain}] — these tell you whether MCP works, which endpoint to use, what query terms match the store's catalog, collection names, product type terminology, and domain corrections.
2. General pattern entries: Lines starting with [pattern:{mode}] — these capture cross-store learnings about what query structures work best for catalog vs. policy searches.

Apply what you find. If the file says [store:allbirds.com] MCP works. Use material terms (wool, tree) not generic terms (comfortable). Collections: running, everyday, hiking. — use that to construct a better query. If there's no entry for this store, proceed with default query construction.

Log it:

exec: bash /home/openclaw/.openclaw/workspace/skills/shopify-nexus/scripts/nexus-log.sh memory_recall domain={shop_domain} memory_hits={number of matching lines found} note="{brief summary of what you recalled, or 'first encounter with this store'}"

Step 4: Stage 1 — Nexus Search (MCP + Storefront)

4a: MCP Discovery & Domain Resolution (first time per store)

If you have NO memory entries for this store's MCP capabilities, start with a discovery fetch. This step also handles self-healing when the domain doesn't work.

Important: Shopify's MCP endpoint uses JSON-RPC 2.0 over HTTP POST — a plain GET returns 404. Always use the MCP client script, which handles the protocol handshake automatically.

Attempt 1: Direct domain

exec: bash /home/openclaw/.openclaw/workspace/skills/shopify-nexus/scripts/shopify-mcp.sh {shop_domain} --discover

If this succeeds, the response contains a JSON-RPC result with a tools array. Each tool has a name, description, and inputSchema. Common tools you'll see:

• search_shop_catalog — product search (takes query and context)
• get_product_details — single product lookup (takes product_id)
• search_shop_policies_and_faqs — policies/FAQs (takes query)
• get_cart / update_cart — cart operations

Log the discovery:

exec: bash /home/openclaw/.openclaw/workspace/skills/shopify-nexus/scripts/nexus-log.sh mcp_discovery domain={shop_domain} status=ok mcp_tools="{comma-separated tool names from the tools array}" payload_bytes={response size in bytes} note="{brief summary of capabilities}"

If this fails (curl error, HTTP error, JSON-RPC error), DO NOT give up. Enter the self-healing resolution chain:

Self-Healing Resolution Chain

Try each fix in order. Stop as soon as one works.

Fix 1 — Try .myshopify.com variant: Many stores have a vanity domain but the MCP endpoint lives on their .myshopify.com subdomain. Extract the brand name and try:

exec: bash /home/openclaw/.openclaw/workspace/skills/shopify-nexus/scripts/shopify-mcp.sh {brand-name}.myshopify.com --discover

For example: allbirds.com → allbirds.myshopify.com, gymshark.com → gymshark.myshopify.com.

Log the attempt:

exec: bash /home/openclaw/.openclaw/workspace/skills/shopify-nexus/scripts/nexus-log.sh domain_correction domain={shop_domain} status={ok|error} correction_from={original} correction_to={attempted} correction_method=myshopify reason="{what happened with original domain}"

Fix 2 — Try with/without www. prefix:

exec: bash /home/openclaw/.openclaw/workspace/skills/shopify-nexus/scripts/shopify-mcp.sh www.{shop_domain} --discover

Or if the user gave www.example.com, try without it.

Log it:

exec: bash /home/openclaw/.openclaw/workspace/skills/shopify-nexus/scripts/nexus-log.sh domain_correction domain={shop_domain} status={ok|error} correction_from={original} correction_to={attempted} correction_method=www

Fix 3 — Verify it's actually a Shopify store: Before giving up on MCP, check if the store is even Shopify by probing the products.json endpoint:

web_fetch https://{shop_domain}/products.json?limit=1

• If this returns Shopify product JSON → the store IS Shopify but MCP may not be enabled. Log and skip to fallback.
• If this also fails → try the .myshopify.com variant for products.json too.
• If nothing works → the domain may not be a Shopify store at all.

Log it:

exec: bash /home/openclaw/.openclaw/workspace/skills/shopify-nexus/scripts/nexus-log.sh domain_correction domain={shop_domain} status={ok|error} correction_method=shopify_verify reason="{what products.json returned}" note="{is it Shopify? is MCP available?}"

Fix 4 — Common misspellings: If the domain looks like a plausible misspelling (e.g., allbird.com without the s, gymshark.co missing the m), try obvious corrections:

• Missing trailing s on brand name → add it
• .co → try .com
• Missing common suffixes → try .com

Log it:

exec: bash /home/openclaw/.openclaw/workspace/skills/shopify-nexus/scripts/nexus-log.sh domain_correction domain={shop_domain} status={ok|error} correction_from={original} correction_to={attempted} correction_method=spelling reason="suspected typo"

If ALL fixes fail — fall back silently. THIS IS MANDATORY, NOT OPTIONAL:

exec: bash /home/openclaw/.openclaw/workspace/skills/shopify-nexus/scripts/nexus-log.sh mcp_discovery domain={shop_domain} status=error reason="exhausted all resolution attempts" note="{summary: which variants tried, what each returned}"

You MUST then:

1. Record [store:{shop_domain}] no MCP. Discovery failed: {reason}. Use web_fetch/browser. Last checked: {date}. in nexus-knowledge.md
2. Immediately fall back to web_fetch or browser — do NOT ask the user anything. Do NOT ask which store to search. Do NOT ask for clarification. Just fetch the store's website and find the products.

Concrete fallback steps (execute these, don't skip them):

web_fetch https://{shop_domain}

If web_fetch returns product data, use it. If web_fetch returns thin content (<500 chars useful text), switch to browser:

browser: action: "open", url: "https://{shop_domain}"
browser: action: "snapshot"

If the homepage doesn't show products, try the search/shop pages:

web_fetch https://{shop_domain}/search?q={url_encoded_query}

or

browser: action: "open", url: "https://{shop_domain}/search?q={url_encoded_query}"
browser: action: "snapshot"

You MUST deliver product results or clearly state "I couldn't find {specific product} on {store}" — NEVER ask the user a question instead of searching.

Example of CORRECT behavior for nike.com:

• MCP handshake fails → log it
• Try nike.myshopify.com → fails → log it
• Try products.json → fails → log it (not Shopify)
• Record [store:nike.com] no MCP in nexus-knowledge.md
• web_fetch https://nike.com/w/running-shoes → get product data → present results
• NEVER say "Do you want me to search Nike.com?" — you already ARE searching it

Example of WRONG behavior (this is a bug):

• MCP fails → "Would you like me to search Nike's official store?" ← THIS IS FORBIDDEN

If a fix succeeds: Use the corrected domain for all subsequent steps. Inform the user: "I found the store at {corrected_domain} (the domain you gave was {original})." Remember the correction in Step 7.

4b: Construct and Execute the Search Query

Based on memory (Step 3) and discovery (Step 4a), construct the best query and call the appropriate MCP tool using the client script.

Level 1 — Basic query (no prior knowledge):

For catalog searches, call search_shop_catalog with the user's query:

exec: bash /home/openclaw/.openclaw/workspace/skills/shopify-nexus/scripts/shopify-mcp.sh {shop_domain} search_shop_catalog query="{user's search terms}" context="browsing"

For policy/FAQ queries (mode: policy), call search_shop_policies_and_faqs:

exec: bash /home/openclaw/.openclaw/workspace/skills/shopify-nexus/scripts/shopify-mcp.sh {shop_domain} search_shop_policies_and_faqs query="{user's policy question}"

For a specific product (when you have a product ID from a prior search):

exec: bash /home/openclaw/.openclaw/workspace/skills/shopify-nexus/scripts/shopify-mcp.sh {shop_domain} get_product_details product_id="{gid://shopify/Product/...}"

Note: The script takes key=value pairs (not raw JSON). Each parameter is a separate argument. Values with spaces must be quoted.

Level 2 — Refined query (after learning the store's catalog structure): Use specific product types, collection handles, or vendor names you've learned from prior searches. Set the context field to include hints (e.g., "context":"looking for wool material running shoes").

Level 3 — Multi-step query (for complex requests):

1. First search broadly to discover collection/category names
2. Then search within the relevant collection with refined terms
3. Optionally call get_product_details for the most relevant products
4. Combine results for a comprehensive answer

Log the search:

exec: bash /home/openclaw/.openclaw/workspace/skills/shopify-nexus/scripts/nexus-log.sh mcp_search domain={shop_domain} query="{actual query sent}" query_level={1|2|3} endpoint=mcp status={ok|error|empty} products={count} payload_bytes={response size} note="{brief: what came back}"

4c: Empty Results — Retry Before Fallback

If the MCP tool call returns zero products (empty content array or no product data), don't immediately fall back. Try one retry with adjusted query terms:

1. If query was specific (e.g., "navy blue wool runners size 10"), broaden it (e.g., "wool runners")
2. If query was vague (e.g., "something comfortable"), add category terms (e.g., "comfortable shoes")
3. If the store uses different terminology (you learned this from discovery), translate the query

Call the MCP script again with the adjusted query:

exec: bash /home/openclaw/.openclaw/workspace/skills/shopify-nexus/scripts/shopify-mcp.sh {shop_domain} search_shop_catalog query="{adjusted terms}" context="{reason for adjustment}"

Log the retry:

exec: bash /home/openclaw/.openclaw/workspace/skills/shopify-nexus/scripts/nexus-log.sh mcp_search domain={shop_domain} query="{adjusted query}" query_level={level} endpoint=mcp status={ok|error|empty} products={count} payload_bytes={response size} note="retry: broadened/narrowed from original query"

4d: Fallback — Legacy Products API

If MCP returns an error or remains empty after retry, fall back:

exec: bash /home/openclaw/.openclaw/workspace/skills/shopify-nexus/scripts/nexus-log.sh search_fallback domain={shop_domain} fallback_reason="{MCP returned 404|MCP empty after retry|MCP timeout|etc}" endpoint=products_json

web_fetch https://{shop_domain}/products.json?q={url_encoded_query}

Additional parameters you can try:

• product_type={type} — filter by product type
• vendor={vendor} — filter by vendor/brand
• collection_id={id} — scope to a collection (if known from prior queries)
• page={n}&limit=25 — paginate for more results

Log the fallback result:

exec: bash /home/openclaw/.openclaw/workspace/skills/shopify-nexus/scripts/nexus-log.sh products_json_search domain={shop_domain} query="{query}" status={ok|error|empty} products={count} payload_bytes={response size} note="{what came back}"

If both MCP and products.json fail:

exec: bash /home/openclaw/.openclaw/workspace/skills/shopify-nexus/scripts/nexus-log.sh error domain={shop_domain} reason="both MCP and products.json failed" note="{details of both failures}"

Record [store:{shop_domain}] no MCP in nexus-knowledge.md, then fall back to web_fetch or browser to answer the user's question directly. Fetch the store's website, find what the user asked about, and present it. Never tell the user the pipeline failed — just deliver the answer.

Step 5: Stage 2 — Context Synthesis (Build Genius Payload)

Construct a JSON payload for the Chatsi Product Genius API. Use the top 3 product names/descriptions from Stage 1 to enrich the query.

{
  "AssistantName": "Shopify Nexus",
  "ChatDateTime": "<current ISO 8601 timestamp>",
  "ChatHistory": [],
  "ChatThreadId": "<generate a UUID>",
  "MerchantName": "<shop_domain>",
  "Options": {
    "ResponseStyle": "concise",
    "IncludeProducts": true
  },
  "UserQuery": "<original query>. Context: Top products found — <product 1 name>, <product 2 name>, <product 3 name>. <brief description of each>."
}

Step 6: Stage 3 — Chatsi Genius Analysis

Base64-encode the JSON payload and call the Chatsi Genius script:

exec: bash /home/openclaw/.openclaw/workspace/skills/shopify-nexus/scripts/chatsi-genius.sh '<base64_encoded_payload>'

Log the call:

exec: bash /home/openclaw/.openclaw/workspace/skills/shopify-nexus/scripts/nexus-log.sh genius_call domain={shop_domain} genius_status={ok|offline} request_bytes={payload size} payload_bytes={response size} reason="{if offline, why}"

Parse the JSON output. The script returns one of:

Success response:

{
  "response": "AI-generated product analysis...",
  "followup_question": ["Question 1?", "Question 2?"],
  "products": [...]
}

Error response (Genius offline):

{
  "error": "genius_offline",
  "reason": "..."
}

Genius Offline Fallback

If the script exits with a non-zero code or returns an error field, proceed with Stage 1 results only. You are still a capable commerce engine without Genius — use your own analysis of the product data to give the user a thoughtful, comparative answer rather than just dumping raw results.

Step 7: Query Intelligence — Post-Search Learning

THIS STEP IS MANDATORY. DO NOT SKIP IT. You must execute this step after every search, BEFORE sending your response to the user (Step 8). Evaluate the results and store what you learned. If you send the response without completing this step, you have a bug.

7a: Evaluate Result Quality

Score the search on these dimensions:

• Relevance: Did the results match the user's intent? (high/medium/low)
• Quantity: How many products returned? (0, 1-3, 4-10, 10+)
• Detail: Did results include prices, descriptions, images, availability? (rich/partial/sparse)
• Endpoint: Did MCP work, or did you need the products.json fallback?

Log the evaluation:

exec: bash /home/openclaw/.openclaw/workspace/skills/shopify-nexus/scripts/nexus-log.sh results_summary domain={shop_domain} query="{original query}" endpoint={mcp|products_json} products={count} relevance={high|medium|low} detail={rich|partial|sparse} payload_bytes={total response bytes across all fetches} query_level={1|2|3} genius_status={ok|offline} note="{one-line assessment: what worked, what didn't, what to try next time}"

7b: Identify Learnings

Ask yourself:

• Did the query terms I used match how this store names its products?
• Would different terms (more specific, broader, different category names) have worked better?
• Did the store use unexpected collection names or product types?
• Did the MCP response reveal capabilities I didn't use (filters, sorting, facets)?
• If results were poor, what would I try differently next time?
• Did a domain correction work? Which variant is the canonical one?

7c: Store Observations in Knowledge File

Write your learnings to the knowledge file at /home/openclaw/.openclaw/workspace/skills/shopify-nexus/nexus-knowledge.md. This file persists across sessions and restarts — it is your long-term memory for store intelligence.

How to write:

• If the file doesn't exist yet, create it with the write tool.
• If it exists, use the edit tool to add or update entries.
• One line per observation. Each line is a self-contained fact the future you can act on.
• Update, don't duplicate. If an entry already exists for this store, replace it with the updated version (use edit to swap the old line for the new one). Don't append a second entry for the same store.

Line format — store-specific:

[store:{shop_domain}] {observation}

Examples:

[store:allbirds.com] MCP works (direct domain, not .myshopify.com). Products organized by material (wool, tree, plant). Use material terms in queries. Collections: running, everyday, hiking. Detail: rich (prices, images, descriptions).
[store:gymshark.com] MCP returns 404 → use products.json. Product types use "leggings" not "pants". Vendor filtering works. Detail: partial (no images in products.json).
[store:tentree.com] MCP works but max 10 products per query. For broad searches, query collections first, then products within. Detail: rich.

Line format — domain corrections:

[domain:{original_domain}] Corrected to {working_domain}. Method: {myshopify|www|spelling}. Original returned: {what happened}.

Line format — stores without MCP (negative learning):

[store:{shop_domain}] no MCP. Discovery failed: {reason}. Use web_fetch/browser. Last checked: {date}.

Examples:

[store:target.com] no MCP. Discovery failed: not a Shopify store (products.json 404). Use web_fetch/browser. Last checked: 2026-02-15.
[store:nike.com] no MCP. Discovery failed: MCP 404, products.json 404, not Shopify. Use web_fetch/browser. Last checked: 2026-02-15.

When you encounter a [store:X] no MCP entry that is more than 14 days old, retry MCP discovery — stores add MCP support over time. Update the Last checked date regardless of the outcome.

Line format — general patterns:

[pattern:catalog] {observation about catalog searches across stores}
[pattern:policy] {observation about policy searches across stores}

Examples:

[pattern:catalog] Specific product category terms ("running shoes" not "comfortable footwear") return 3-5x more results across most stores.
[pattern:catalog] Stores using Shopify Dawn theme tend to have richer MCP responses with full product descriptions.
[pattern:policy] Most stores expose policies via shopify://store/policies resource. Query "shipping policy" directly, not "how long does delivery take".

After writing, log it:

exec: bash /home/openclaw/.openclaw/workspace/skills/shopify-nexus/scripts/nexus-log.sh memory_store domain={shop_domain} note="{what was stored or updated}"

7d: What NOT to Store

• Don't store specific product data (prices change, inventory changes)
• Don't store the raw query or response content
• Don't store user-identifying information
• Only store structural patterns about how the store's data is organized and how to query it effectively

Step 8: Response Formatting & Final Log

CHECKPOINT: Before writing your response, confirm you completed Step 7. Did you write to nexus-knowledge.md? Did you log results_summary and memory_store? If not, go back and do it now. The response is the LAST thing you do, not the first.

When Genius is available:

1. Main analysis: Display the response field as the primary answer.
2. Follow-up suggestions: Show followup_question items as "You might also want to ask:" bullet points.
3. Product cards: For each product, show:
   • Product name (linked if URL available)
   • Price
   • Brief description
   • Availability status

When Genius is offline (standalone mode):

Provide your own intelligent analysis of the product results:

1. Direct answer: Address the user's specific question using the product data you retrieved.
2. Product comparison: If multiple products match, compare them on relevant dimensions (price, features, ratings if available).
3. Recommendations: Based on the user's query intent, highlight which products seem most relevant and why.
4. Product details: For each recommended product, show name, price, description, and availability.
5. Follow-up suggestions: Offer 2-3 natural follow-up questions the user might want to ask (e.g., "Want me to check sizing options?" or "Should I look at similar products in a different price range?").

Do NOT say "AI analysis is temporarily unavailable" or suggest trying again later. You ARE the AI analysis. Genius is an optional enrichment layer, not a requirement.

Step 8b: Send Product Images to Telegram

MANDATORY — After composing your text response, send the top product images as inline photos so the user sees them directly in chat. Do NOT skip this step.

For each of the top 1–3 products that have an image URL in the MCP response data, run:

exec: bash /home/openclaw/.openclaw/workspace/scripts/send-photo.sh "{image_url}" "<b>{product_name}</b> — {price}"

• Send images AFTER your text reply, not before
• Captions support HTML: use <b>bold</b> for product names, <a href="url">link</a> for shop links
• Strip any whitespace or newlines from image URLs before passing them
• If an image URL is missing or broken, skip that product silently (do not mention the failure)
• Maximum 3 images per response to keep the chat clean on mobile

Log completion:

exec: bash /home/openclaw/.openclaw/workspace/skills/shopify-nexus/scripts/nexus-log.sh search_complete domain={shop_domain} query="{original query}" products={total products in final response} endpoint={mcp|products_json} genius_status={ok|offline} query_level={1|2|3} relevance={high|medium|low}

Important Notes

• Always validate the domain before making any external request.
• Never expose raw API errors, credentials, internal endpoints, or log file contents to the user.
• If the store has no results for the query, say so clearly rather than making up products.
• The Chatsi Genius API is optional — the skill is fully functional with just MCP data and your own analysis.
• Each query is a learning opportunity. The memory step (Step 7) is not optional — always evaluate and store observations after a search, even if the search was straightforward.
• Logging is not optional. Every step must produce a log entry. This is how we monitor search quality, identify failing stores, and track the skill's improvement over time.
• The knowledge file at /home/openclaw/.openclaw/workspace/skills/shopify-nexus/nexus-knowledge.md is your persistent brain. It survives restarts, syncs, and session boundaries. Every [store:...] and [pattern:...] entry you write makes the next query to that store faster and more accurate. Read it at the start of every search, write to it at the end of every search. This is how you get smarter over time.