clawauto-shop（爪汽车店）

KFC/McD clawauto-shop Skill（2.0.0）

Automates KFC and McDonald's order-link flows after backend returns a cdkey URL.

仅需查询：若只需 查询商品信息 与 查询个人信息，请使用 1.0.0 目录：../1.0.0/。

Upload Readiness (ClawHub)

• Self-contained under this folder (openclaw_skill.py, kfc_place_order_test_old.py, kfc_custom_product_flow.py, kfc_vip_choose_spec_flow.py, mcd_place_order_test.py, mcd_custom_product_flow.py, requirements.txt).
• No hardcoded local paths.
• Outputs are written to skill/outputs/ (or current dir).
• Can run with user-configured phone + api key.

Required Runtime Config

Use either CLI args or environment variables. For OpenClaw usage, .env is recommended:

Env-based config (dev / prod)

Create .env manually in this folder, then paste and modify:

KFC_PLATFORM_ENV=dev
KFC_PLATFORM_PHONE=13800138000
KFC_PLATFORM_API_KEY=your_api_key_here
KFC_PLATFORM_BASE_URL_DEV=http://localhost:8888/api/openclaw
KFC_PLATFORM_BASE_URL_PROD=https://www.clawauto.shop/api/openclaw
KFC_PLATFORM_BASE_URL=http://localhost:8888/api/openclaw
# Optional:
# KFC_PLATFORM_USERNAME=your_username

Then configure:

• Environment:

- KFC_PLATFORM_ENV: dev / prod (default dev)

• Backend base URL:

- KFC_PLATFORM_BASE_URL_DEV: dev backend, default http://localhost:8888/api/openclaw - KFC_PLATFORM_BASE_URL_PROD: prod backend, default https://www.clawauto.shop/api/openclaw - KFC_PLATFORM_BASE_URL: common base URL fallback

• Identity & API key:

- KFC_PLATFORM_PHONE: user phone - KFC_PLATFORM_API_KEY: API key - optional KFC_PLATFORM_USERNAME

When running inside OpenClaw, .env will be loaded automatically, so you don't need to type these each time.

CLI vs env

• Identity:

- --phone or KFC_PLATFORM_PHONE - (fallback) --username or KFC_PLATFORM_USERNAME

• API key:

- --api-key or KFC_PLATFORM_API_KEY

• Backend URL:

- --base-url or KFC_PLATFORM_BASE_URL - default: http://localhost:8888/api/openclaw

Runtime Chain

1. Optional: GET /health 探活（无鉴权，独立限流）。
2. Query platform products (POST /products).
3. Optional: POST /orders 拉取当前用户订单列表（与网页端「我的订单」同源）。
4. User selects product_id (or supplier_goods_id for supplier-only SKUs).
5. Skill calls platform order (POST /order)，请求体可带 idempotency_key，或使用 HTTP 头 Idempotency-Key。
6. After order: use POST /order/status with order_id to poll supplier status / refreshed meal URL (openclaw_skill.py --fetch-order-status <id>).
7. Skill auto-runs browser order flow based on returned flow or URL host.
8. Stops before final submit by default unless explicitly allowed.

OpenClaw JSON 错误体含 message + code（如 OPENCLAW_UNAUTHORIZED、OPENCLAW_RATE_LIMITED）；成功响应带 X-OpenClaw-RateLimit-Remaining / X-OpenClaw-RateLimit-Limit，限流时另有 Retry-After。

Flow 识别规则（OpenClaw 调用时据此选择脚本）

主程序会输出一行 flow_detected: <flow_code> -> <script> 便于日志与校验。

Required Per-Run Inputs (purchase flow)

• --product-id
• --store-keyword
• KFC flow only: --city

Optional:

• --store-name
• --pickup-type (default Dine-in for McD / 外带 for KFC)
• --pickup-time (empty => immediate pickup)
• --eat-type (McD only, default Dine-in)
• --kfc-store-code (肯德基门店编号如 SHA391，VIP/customProduct 不填则用 city+store-keyword 调 API)
• --booking-time (肯德基 customProduct 预定时间编码，0=立即取餐)
• --mcd-store-number (麦当劳 customProduct 直接填门店编号，不填则用 store-keyword 调 API)
• --wait-pickup-seconds (麦当劳/肯德基 VIP 等待取餐码最大秒数，默认 60)
• --list-products (query only, no purchase)
• --skip-flow (return link only)
• --allow-final-submit (explicitly allow clicking final confirm)
• --no-final-submit (force stop; safety mode already stops)

Install

pip install -r requirements.txt
python -m playwright install chromium

Backend Requirement

Backend endpoint must be reachable:

• KFC_PLATFORM_BASE_URL or default http://localhost:8888/api/openclaw
• POST /api/openclaw/products: accepts username/phone + api_key
• POST /api/openclaw/order: validates balance (yuan), deducts cost, returns order link + cost_yuan / balance_yuan
• 肯德基 VIP 链接：GET /api/openclaw/kfc/store?city=xxx&keyword=xxx 返回 {"store_code": "SHA391"}（或 storeCode/store）
• 麦当劳 customProduct：GET /api/openclaw/mcd/store?keyword=xxx 返回 {"store": "1450468"}

Quick Start (recommended with env)

set KFC_PLATFORM_PHONE=13800138000
set KFC_PLATFORM_API_KEY=your_api_key

python openclaw_skill.py --list-products

Then purchase and auto-order:

python openclaw_skill.py --product-id 1 --city 上海 --store-keyword 金地新华道

肯德基 customProduct 链接（kfc.woaicoffee.cn/?cdkey=...）

当订单链接为 肯德基 customProduct 格式（https://kfc.woaicoffee.cn/?cdkey=...，且不是已带 customProduct 的完整链接）时，Skill 会：

1. 转换链接：用 --city + --store-keyword 调用后端 GET /kfc/store?city=xxx&keyword=xxx 获取门店编号，或直接使用 --kfc-store-code；--booking-time 为预定时间编码（默认 0=立即取餐）。生成：

https://kfc.woaicoffee.cn/index/index/customProduct?cdkey=...&store=...&booking_time=...

1. 浏览器流程：打开转换后的链接 → 点击页面最下方红色「确认提交」→ 弹窗点「确认」完成下单 → 等待订单成功页、识别取餐码并截图，输出简要信息。
2. 输出：取餐码、订单号、截图路径等通过 print_chat_report 输出给用户。

必填：--city 与 --store-keyword（用于查门店）或 --kfc-store-code。 可选：--booking-time（默认 0，立即取餐）、--wait-pickup-seconds（默认 60）。

肯德基 VIP 兑换链接（vip.woaicoffee.com）

当订单链接为 肯德基 VIP 格式（https://vip.woaicoffee.com/?outId=xxx）时，Skill 会：

1. 浏览器步骤：打开链接 → 点击「下一步」→ 若有定位权限弹窗则点击「访问该网站时允许」→ 从当前访问链接解析 productId。
2. 转换链接：用 --city + --store-keyword 调用后端 GET /kfc/store?city=xxx&keyword=xxx 获取门店编号 storeCode，或直接使用 --kfc-store-code；生成：

https://vip.woaicoffee.com/kfc/choose_specifications?outId=xxx&productId=393&storeCode=SHA391&sendPhoneMsg=false

1. 下单：打开上述链接 → 点击「下单」→ 二次确认弹窗点击「确认」→ 等待页面刷新出现取餐码（最多 --wait-pickup-seconds 秒）→ 将取餐信息返回用户。

必填：--city 与 --store-keyword（用于查门店）或 --kfc-store-code（直接填门店编号如 SHA391）。 可选：--wait-pickup-seconds（默认 60）。

麦当劳 customProduct 链接（门店自提）

当订单链接为 麦当劳 customProduct 格式（https://mdl.woaicoffee.cn/?cdkey=...，且不是已带 customProduct 的完整链接）时，Skill 会：

1. 转换链接：用 --store-keyword 调用后端 GET /mcd/store?keyword=xxx 获取门店编号，或直接使用 --mcd-store-number；eat_type 固定为 门店自提，生成：

https://mdl.woaicoffee.cn/index/index/customProduct?cdkey=...&store=...&eat_type=门店自提

1. 浏览器流程：打开转换后的链接 → 点击页面底部红色「下单」→ 弹窗「请再次确认门店信息是否正确」中点击蓝色「就是这个餐厅」（不点「返回重选」）→ 等待下单成功页，最多 1 分钟 内获取取餐码/订单号。
2. 输出：取餐信息、订单号、截图路径等通过 print_chat_report 输出给用户。

必填：--store-keyword（用于查门店）或 --mcd-store-number（直接填门店编号）。 可选：--wait-pickup-seconds（默认 60，等待取餐码最大秒数）。

断连与恢复（大模型异常时在聊天框展示结果）

当 OpenClaw 大模型断连或订单执行停滞时：

1. 订餐链接已返回时：Skill 在获得订餐链接后会立即输出可解析行，便于客户端/大模型从已有输出中提取并展示给用户：

- 标准输出中会有一行以 OPENCLAW_FINAL_LINK: 开头的订餐链接。 - 另有一行 OPENCLAW_ORDER_STATE: 开头的 JSON，含 url、order_id、stage 等。 - 建议：大模型或调用方在断连、超时、异常时扫描本次调用的 stdout，若匹配到 OPENCLAW_FINAL_LINK:，则直接在用户聊天框展示该链接，并提示「订单已生成订餐链接，请点击使用」。

1. 订单状态保存在用户本地：每次下单/流程推进都会把当前阶段写入本地目录（默认 skill/2.0.0/openclaw_order_state/，可通过环境变量 OPENCLAW_ORDER_STATE_DIR 覆盖）。保存内容包括：order_id、url、stage（order_received / flow_running / flow_done / flow_failed）、取餐码等。该目录含订餐链接等敏感信息，已加入 .gitignore，请勿提交到版本库。

1. 恢复后查询进度：大模型恢复或用户询问「订单到哪了」时，可再次调用 Skill 的查询模式，从本地读取并返回当前阶段与订餐链接：

- 按幂等键查询：--query-order <idempotency_key>（与下单时使用的 --idempotency-key 一致）。 - 按订单 ID 查询：--query-order-by-id <order_id>。 - 列出本机最近订单：--list-local-orders 输出最近约 20 条本地订单的 order_id、阶段、更新时间与链接摘要，用户说「我最近的订单」时先调此接口，再按 order_id 用 --query-order-by-id 查详情。 - 查询会输出阶段说明、订餐链接（若有）以及取餐码/订单号（若流程已跑完），并再次输出 OPENCLAW_FINAL_LINK: 行便于展示。

解析订餐链接（供调用方/大模型实现）：从 Skill 的 stdout 中取第一行包含 OPENCLAW_FINAL_LINK: 的整行，冒号后到行尾的字符串 trim 后即为订餐链接 URL；可直接展示给用户或写入聊天框。

建议：调用方在下单时传入固定的 --idempotency-key（例如由会话 ID 或用户 ID 生成），断连后即可用 --query-order <该 key> 查询同一笔订单，无需用户提供 order_id。

示例（查询本地进度）：

python openclaw_skill.py --list-local-orders
python openclaw_skill.py --query-order abc123def456
python openclaw_skill.py --query-order-by-id 10086

报错与处理建议

流程脚本会在结果 JSON 中写入 error（详情）和 error_code（标准码）。主程序失败时会根据 error_code 输出处理建议。