Mai
Overview
Mai helps buyers and merchants complete shopping matchmaking through an AI agent. It keeps deterministic marketplace state in scripts/mai.py while the host model handles natural language, negotiation, summaries, and risk explanations.
Mai can run local-only or registry-backed. Use local-only for one agent's private catalog. Use registry-backed discovery when buyers and merchants are on different machines or agent profiles.
Operating Principles
- Be neutral between buyer and merchant. Explain options, prices, review signals, inventory, and tradeoffs without fabricating availability.
- Treat payments as external or PSP-backed. Mai never directly holds funds. Local mode records payment URLs and references; registry mode records PSP custody events and must not claim success without PSP or external evidence.
- Confirm before irreversible steps. Ask for buyer confirmation before creating an order and merchant confirmation before reserving stock.
- Preserve negotiation context. Record important buyer/merchant messages with
message addbefore forming or updating an order. - Surface risk plainly: no reviews, low stock, missing merchant contact, unusual status jumps, unclear payment terms, and unsupported refund promises.
- Prefer short, actionable answers: recommendation, reason, risk, next action.
Quick Start
Use the CLI helper for deterministic state:
python3 scripts/mai.py merchant create --id seller-a --name "West Lake Tea" --city Hangzhou --contact "wechat:westlake" --tags "tea,gift"
python3 scripts/mai.py product add --merchant seller-a --sku tea-a --title "Longjing Gift Box" --price 88 --stock 5 --category tea --tags "longjing,gift"
python3 scripts/mai.py search products --query "longjing tea" --format json
python3 scripts/mai.py compare --skus tea-a,tea-b --format json
python3 scripts/mai.py order create --buyer alice --merchant seller-a --sku tea-a --quantity 2 --offer-price 86
Default data path: ~/.local/share/mai/mai.json.
Use --data /path/to/mai.json for a project-local or test database.
Installation
Install the published OpenClaw pair:
clawhub --workdir ~/.openclaw/workspace --dir skills install mai
openclaw plugins install clawhub:mai-plugin
mai is the skill. mai-plugin is an optional lightweight OpenClaw native bridge for tools and /mai command support.
Local checkout install:
cd /Users/jianghaidong/coding/mai
bash scripts/install.sh --both
Install only one ecosystem:
bash scripts/install.sh --openclaw
bash scripts/install.sh --hermes
The installer creates symlinks:
- OpenClaw:
~/.openclaw/workspace/skills/mai - Hermes:
~/.hermes/skills/commerce/mai
After installation, restart the host agent if it does not refresh skills automatically. Hermes can preload Mai with hermes -s mai.
Registry Discovery
Run a registry marketplace:
python3 scripts/mai_registry.py issue-key --data ./mai-registry.json --token admin-token --role admin --subject ops-admin
python3 scripts/mai_registry.py issue-key --data ./mai-registry.json --token seller-token --role merchant --subject seller-a --merchant-id seller-a
python3 scripts/mai_registry.py issue-key --data ./mai-registry.json --token buyer-token --role buyer --subject alice --buyer-id alice
python3 scripts/mai_registry.py serve --data ./mai-registry.json --host 127.0.0.1 --port 8765 --rate-limit-per-minute 60
Merchant agents publish local supply:
python3 scripts/mai.py --data ./seller.json registry push --url http://127.0.0.1:8765 --api-key seller-token
Buyer agents discover supply and create demand:
python3 scripts/mai.py --data ./buyer.json registry search-products --url http://127.0.0.1:8765 --query "longjing tea" --format json
python3 scripts/mai.py --data ./buyer.json registry message --url http://127.0.0.1:8765 --api-key buyer-token --buyer alice --merchant seller-a --sku tea-a --text "Can this ship today?"
python3 scripts/mai.py --data ./buyer.json registry order --url http://127.0.0.1:8765 --api-key buyer-token --buyer alice --merchant seller-a --sku tea-a --quantity 2 --offer-price 86
python3 scripts/mai.py --data ./buyer.json registry payment-hold --url http://127.0.0.1:8765 --api-key buyer-token --buyer alice --order ORD-0001
Merchant agents pull buyer messages and draft orders:
python3 scripts/mai.py --data ./seller.json registry pull --url http://127.0.0.1:8765 --api-key seller-token --merchant seller-a
Read references/registry-api.md before changing registry integrations.
Public Marketplace Controls
- Require API keys for merchant push/pull, buyer messages/orders/payment holds, moderation, and payment release/refund.
- Store only salted API key hashes in the registry file.
- Allow public search, but rate-limit every request by API key or client IP.
- Treat products with high risk scores as
pending_review; do not show them in search until an admin approves them. - Use
registry payment-holdonly as PSP-backed custody tracking. The bundleddemoprovider is not real money movement. - Require an admin key for
registry payment-releaseandregistry payment-refund. - Do not claim escrow, payment success, release, or refund unless the PSP adapter or external evidence confirms it.
Merchant Workflow
- Create or identify the merchant profile:
python3 scripts/mai.py merchant create --id ID --name NAME --city CITY --contact CONTACT --tags "A,B" - Publish products:
python3 scripts/mai.py product add --merchant ID --sku SKU --title TITLE --price N --stock N - Adjust stock after physical changes:
python3 scripts/mai.py product stock --sku SKU --merchant ID --adjust N --reason "restock or correction" - Record important buyer questions and seller replies:
python3 scripts/mai.py message add --buyer BUYER --merchant ID --sku SKU --sender merchant --text "..." - Quote and confirm orders only when inventory and terms are clear:
python3 scripts/mai.py order quote ...python3 scripts/mai.py order update --order ORD-0001 --status confirmed --actor merchant
Buyer Workflow
- Discover merchants:
python3 scripts/mai.py search merchants --query "tea hangzhou" --format json - Search products:
python3 scripts/mai.py search products --query "longjing gift" --max-price 100 --format json - Compare shortlisted SKUs:
python3 scripts/mai.py compare --skus sku-a,sku-b --format json - Inspect reviews:
python3 scripts/mai.py review list --merchant ID --format json - Record discussion before ordering:
python3 scripts/mai.py message add --buyer BUYER --merchant ID --sku SKU --text "..." - Create a draft order after buyer confirmation:
python3 scripts/mai.py order create --buyer BUYER --merchant ID --sku SKU --quantity N
Transaction Model
Mai tracks transactions without custody:
draft -> quoted -> confirmed -> payment_pending -> paid_external -> fulfilled -> completed
Disputes can move through:
disputed -> resolved/refunded/cancelled
Stock is reserved when an order becomes confirmed. Local-only payments are recorded as payment_url and payment_reference. Registry payments are PSP custody records; the agent must say the bundled demo provider is not real escrow or money movement.
Read references/transaction-model.md when handling non-happy-path order, refund, dispute, or payment questions.
Read references/data-schema.md when integrating Mai with a future hosted marketplace or sync service.
Output Expectations
For product discovery, answer with:
- best match and why
- price and merchant comparison
- availability and shipping notes
- review/trust signals
- risks or missing facts
- one next action
For merchant operations, answer with:
- action completed or blocked
- changed product/order/inventory identifier
- current stock or status
- next operational step
For order updates, answer with:
- previous status and new status
- whether stock was reserved or released
- payment evidence recorded, if any
- what must happen next
Verification
Before claiming the package is ready:
python3 scripts/mai.py --helppython3 scripts/mai_registry.py --helpbash scripts/install.sh --both --dry-runpython3 -m unittest discover -s testsbash scripts/verify.sh- Confirm
SKILL.mdhas no scaffold placeholders. - Confirm
README.md,package.json,clawhub.json,plugins/mai-plugin/openclaw.plugin.json, andagents/openai.yamluse themaiandmai-pluginnames consistently.