| name | online-shopping |
| description | Browse and buy products from online stores, including Cloudflare-protected sites. Use when the user asks to find, compare, or order products online. Handles product search, price comparison, adding to cart, filling checkout forms, and navigating to payment. Uses a stealth browser (Patchright) to bypass bot detection. |
Online Shopping
Overview
Search for products, compare options, and complete purchases on online stores — even those protected by Cloudflare. Uses Patchright (stealth Playwright) to avoid bot detection.
First-Time Setup
Run the setup script to install all dependencies:
bash <skill-dir>/scripts/setup.sh
This installs xvfb, Patchright, and Chromium, then verifies everything works. See references/setup.md for manual steps or troubleshooting.
Workflow
- Understand the request — product type, specs, size, brand preference, budget
- Browse the store — use stealth browser script to search and extract product listings
- Recommend — present options with price, availability, ratings. Give a clear recommendation.
- Confirm — get explicit approval before adding to cart
- Checkout — fill shipping/contact details, select delivery and payment
- Stop before paying — always confirm with the user before completing a purchase
Using the Stealth Browser
All browsing goes through Patchright scripts executed with xvfb-run. Do NOT use OpenClaw's built-in browser tool for Cloudflare-protected sites — it connects via CDP which leaks Runtime.enable calls that Cloudflare detects.
Quick browse (bundled script)
xvfb-run --auto-servernum node <skill-dir>/scripts/browse.mjs "<url>" --screenshot /tmp/page.png --text
Custom scripts
Write .mjs scripts in /tmp/ for multi-step flows. Auto-detect Patchright path:
import { createRequire } from 'module';
import { execSync } from 'node:child_process';
import { existsSync } from 'node:fs';
function findPatchright() {
const root = execSync('npm root -g 2>/dev/null').toString().trim();
const candidates = [
root + '/openclaw/node_modules/patchright',
process.env.HOME + '/.npm-global/lib/node_modules/openclaw/node_modules/patchright',
root + '/patchright',
];
for (const p of candidates) {
try { if (existsSync(p)) return p; } catch {}
}
throw new Error('Patchright not found. Run setup.sh first.');
}
const require = createRequire(import.meta.url);
const { chromium } = require(findPatchright());
const browser = await chromium.launchPersistentContext('/tmp/patchright-ctx', {
headless: ,
: ,
: [, ],
});
page = browser.()[] || browser.();
browser.();
Execute with: xvfb-run --auto-servernum node /tmp/my-script.mjs
Critical best practices (from Patchright docs)
These are essential for avoiding bot detection:
headless: false — always. Cloudflare fingerprints headless mode. Use xvfb for servers without a display.viewport: null — let the browser use its natural viewport. Custom viewports are a detection signal.- Do NOT set custom
userAgent or HTTP headers — fingerprint injection makes you more detectable, not less.
- Use persistent context (
launchPersistentContext) — retains cookies, localStorage, and session state between runs. Also more closely resembles real browser behavior.
- Prefer Google Chrome over Chromium where available (x86_64:
npx patchright install chrome, then channel: "chrome"). Chromium has subtle fingerprint differences. ARM64 only supports Chromium.
- Do NOT use
connectOverCDP() — connecting via raw CDP bypasses Patchright's patches. Always use chromium.launch() or chromium.launchPersistentContext().
Why Patchright works where Playwright doesn't
Patchright patches three key detection vectors:
- Runtime.enable leak — Playwright uses
Runtime.enable CDP call which sites detect. Patchright executes JS in isolated execution contexts instead.
- Command flag leaks — Removes
--enable-automation, adds --disable-blink-features=AutomationControlled.
- Console.enable leak — Disables console API to avoid detection (console.log won't work in page context).
Script workflow for shopping
- Search script — navigate to store, search for product, extract listings as text
- Product script — click into a product page, get details
- Cart script — add to cart, navigate to checkout
- Checkout script — dump form fields with
page.evaluate(), fill details, select shipping/payment
- Screenshot — always screenshot before completing purchase for user confirmation
Write each step as a separate .mjs script in /tmp/. Persistent context means the cart and session carry over between scripts.
Debugging tips
- Use
page.screenshot() liberally to see what the page looks like
- Use
page.evaluate(() => document.body.innerText) to dump page text
- Dump form fields with
page.evaluate(() => { ... querySelectorAll('input') ... }) before filling
- Some fields may be read-only (auto-filled from other fields) — check before trying to fill
- Use
page.waitForTimeout() generously — sites need time to load/render
- Close cookie banners early — they can block interactions
User Details & Preferences
Check references/preferences.md for saved shopping data (addresses, payment methods, delivery preferences, order history). If it doesn't exist yet, copy references/preferences-template.md to references/preferences.md and fill it in.
Fall back to USER.md for basic contact/address info.
When checkout requires info not on file, ask the user. After a successful order, update references/preferences.md with:
- Any new address or delivery preference
- The order in the history table
Never store card numbers or sensitive payment credentials. Only store method names (e.g. "Swish", "PayPal", "Visa ending 4321").
Safety
- Never complete a purchase without explicit user confirmation
- Show the cart summary, total price, and shipping cost before final step
- Screenshot the checkout page and describe it to the user
- If something looks wrong (wrong product, unexpected charges), stop and ask
Site-Specific Notes
See references/sites.md for store-specific quirks and tips. If the file doesn't exist yet, copy references/sites-template.md to get started.
