核心用法
agent-commerce-engine 是一个生产级的通用代理电商引擎，旨在通过标准化协议连接自主代理与兼容的无头电商后端。其核心架构基于声明式 API 优先策略，代理通过 commerce.py CLI 脚本与后端交互，支持产品发现、购物车操作、用户管理与订单创建全流程。
关键操作流程：
1. 产品发现：使用 search 或 list 命令获取商品目录，支持 --page 和 --limit 分页参数避免上下文溢出
2. 购物车管理：add-cart/update-cart/remove-cart 提供原子级控制，变体规格必须严格匹配后端可用选项
3. 订单创建：create-order 生成待支付订单并返回支付 URL，代理必须将支付环节移交用户完成（因缺乏金融授权）
4. 身份管理：Token 认证机制，支持 get-profile/update-profile 管理用户资料
显著优点
- 协议标准化：提供
SERVER_SPEC.md规范，任意电商后端实现该接口即可支持代理驱动，无需为每个品牌定制工具 - 生产就绪：Lafeitu Gourmet 等真实案例验证，具备完整的品牌故事、企业信息、客服渠道查询能力
- 安全架构：本地凭证隔离存储（
0600权限）、HTTPS 强制、Token 置换机制（v1.4.0+ 不存原始密码） - 无状态设计：通过
x-user-account/x-visitor-id头部维护会话，避免 Cookie 依赖
潜在局限与风险
- 支付天花板：代理无法直接执行支付（银行卡/移动钱包），必须人工介入完成最终交易，限制完全自动化场景
- 后端兼容性：功能深度依赖目标后端对
SERVER_SPEC.md的实现完整度，非标准后端需二次开发 - Token 生命周期：凭证过期后需重新
login，跨设备同步需手动迁移~/.openclaw/credentials/目录 - 变体验证严格：
VARIANT_UNAVAILABLE错误要求代理必须预校验产品选项列表，增加交互复杂度
适合人群
- 需为 AI 助手集成电商能力的开发者与品牌方
- 运营无头电商（Headless Commerce）架构的技术团队
- 追求"一个工具对接多品牌"的代理平台构建者
常规风险提醒
⚠️ 绝对禁止代理代用户完成支付：create-order 返回的支付 URL 必须由用户亲自打开并授权，代理触碰金融凭证将导致严重合规与资金风险。建议在工作流中设置强制中断点，明确区分"代理准备订单"与"用户确认支付"两个阶段。