快速开始 - Clawdot虾点·文档中心

Clawdot Gateway 把外卖能力以 MCP 工具的形式开放给 AI Agent。本指南带你先连上 MCP，再用一串工具调用从零跑通一次完整下单。

1. 连接 MCP

网关以 Streamable HTTP（FastMCP）对外提供 MCP 服务：

Endpoint：https://eleme-gateway.hicaspian.com/mcp/v1
传输：Streamable HTTP
连接层认证：每个 MCP 请求都带请求头 Authorization: Bearer clw_your_api_key

在 Clawdot 控制台创建 Agent、开通外卖能力，即可拿到 API Key（clw_ 前缀）。把它配进你的 MCP 客户端：

{
  "mcpServers": {
    "clawdot-eleme": {
      "url": "https://eleme-gateway.hicaspian.com/mcp/v1",
      "type": "http",
      "headers": {
        "Authorization": "Bearer clw_your_api_key"
      }
    }
  }
}

连接成功后，你的 Agent 就能看到外卖 MCP 的这 24 个工具。跑腿（同城帮送）是另一套独立 endpoint 的 19 个工具，接法见跑腿 MCP。

两层身份：连接层的 API Key（clw_ 前缀）标识你的 Agent，每个 MCP 请求都要带；consent grant（cg_ 前缀）标识已授权的外卖用户，作为业务工具的参数 consent_grant_id 传入（不走请求头）。绑定类工具 request_user_bind / verify_user_bind 例外——它们是拿授权的入口，本身不传 consent_grant_id。详见认证机制。

2. 用 MCP 工具下单

示例以 工具名 + JSON 参数 给出。除绑定工具外，每个业务工具的参数都带 consent_grant_id。

绑定用户授权

下单要代表一个真实外卖用户，先让 ta 授权（SMS 验证码模式）。绑定工具只需 Agent 身份（连接层 API Key），不传 consent_grant_id。

// 工具：request_user_bind —— 发起绑定，用户收到验证码
{
  "phone": "18800000000",
  "auth_type": "sms"
}
// → { "bind_id": "...", "expires_in": ..., "masked_phone": "188****0000" }

// 工具：verify_user_bind —— 用户告知验证码后确认，铸造 consent_grant_id
{
  "auth_type": "sms",
  "bind_id": "<上一步的 bind_id>",
  "code": "123456"
}
// → { "bound": true, "consent_grant_id": "cg_...", "scopes": [...], "expires_at": "..." }

拿到 consent_grant_id 后，下面每个业务工具调用都带它。

也支持 H5 模式：request_user_bind(auth_type="h5") 返回 h5_url，用户打开完成授权，再 verify_user_bind(auth_type="h5", request_id) 轮询直到拿到 consent_grant_id。见发起绑定。

确定收货地址

先定下”送到哪里”，拿到 address_id 后再按地址搜可送达的店铺。

// 工具：search_addresses —— 搜地址，拿建议（每条含 token）
{
  "consent_grant_id": "cg_your_consent_grant",
  "keyword": "上海市黄浦区人民广场"
}
// → { "suggestions": [ { "token": "...", ... } ] }

// 工具：select_address —— 选定/保存地址，拿 address_id
// 用建议新建地址时，收货人信息为必填
{
  "consent_grant_id": "cg_your_consent_grant",
  "suggestion_token": "<上一步 suggestions[].token>",
  "contact_name": "张三",
  "contact_phone": "13800000000",
  "address_detail": "3 号楼 101"
}
// → { "address_id": "...", "display_name": "...", "lat": ..., "lng": ... }

也可直接用已有地址的 address_id。这个 address_id 既用于下一步搜店，也用于后续算价 / 预览。

搜索店铺

// 工具：search_shops
{
  "consent_grant_id": "cg_your_consent_grant",
  "address_id": "<来自选址>",
  "keyword": "瑞幸咖啡"
}
// → { "shops": [ { "shop_id": "...", "cart_id": "...", "name": "...", ... } ], "next_offset": ... }

按收货地址搜可送达的店铺（address_id 与 lat/lng 二者至少给一个）。每个店铺带 shop_id 和 cart_id（cart_id 已封装店铺与配送坐标，后续步骤原样回传）。不传 keyword 即按附近浏览（≤20 家）。

查看菜单、选商品

// 工具：get_shop_menu
{
  "consent_grant_id": "cg_your_consent_grant",
  "shop_id": "<来自搜索>",
  "cart_id": "<来自搜索>"
}
// → items[]：每项含 item_id / sku_id / ingredient_options；has_more 指示是否还有更多

支持 keyword / limit / offset 渐进加载。记下要买的 item_id 和 sku_id。

算价（购物车报价）

// 工具：quote_cart
{
  "consent_grant_id": "cg_your_consent_grant",
  "shop_id": "<来自搜索>",
  "cart_id": "<来自搜索>",
  "address_id": "<来自选址>",
  "items": [{"item_id": "<来自菜单>", "sku_id": "<来自菜单>", "quantity": 1}]
}
// → { "quote_id": "...", "can_checkout": true, "payable_price": 1500 }

所有金额字段单位为分（整数），1500 表示 ¥15.00。

预览订单

// 工具：preview_order
{
  "consent_grant_id": "cg_your_consent_grant",
  "shop_id": "<来自搜索>",
  "cart_id": "<来自搜索>",
  "address_id": "<来自选址>",
  "items": [{"item_id": "<来自菜单>", "sku_id": "<来自菜单>", "quantity": 1}],
  "quote_id": "<来自算价>"
}
// → { "preview_id": "prv_...", "confirmation_token": "cf_...", "price": {...}, "available_coupons": [...] }

当前订单可用券以返回的 available_coupons 为准。要用券时，选中 available_coupons[].coupon_id，再带 coupon_ids=[...] 重新调一次 preview_order 即可重算（账户级券列表可用 list_coupons 查看）。

正式下单

用预览返回的 preview_id + confirmation_token（confirmation_token 即幂等键）：

// 工具：create_order
{
  "consent_grant_id": "cg_your_consent_grant",
  "preview_id": "prv_...",
  "confirmation_token": "cf_..."
}
// → { "order_id": "ord_...", "status": "...", "payment_action": {...} }

可选传 callback_url：这笔单每次状态变化都会推一条回调，支付结果那条为 event=order_payment。

查询订单

下单后可随时查询订单当前状态与详情。

// 工具：get_order_status —— 查询订单状态
{
  "consent_grant_id": "cg_your_consent_grant",
  "order_id": "ord_..."
}
// → { "status": "...", "status_text": "...", ... }

免密支付签约（账户级，一次性）：免密支付需用户先完成一次签约，签约后续免密订单即自动扣款。它是账户级、一次性的前置设置，不绑定某一笔订单、也不是每单都做——独立于上面的下单链路。用 get_sign_action(consent_grant_id, return_url)（入参不含 order_id）拿到 H5 签约链接交给用户完成，再用 get_sign_status 查询签约进度。详见发起免密签约。

完整链路一览

select_address（得 address_id）→ search_shops（用 address_id，得 shop_id + cart_id）→ get_shop_menu（得 item_id / sku_id）→ quote_cart（得 quote_id）→ preview_order（得 preview_id + confirmation_token）→ create_order（得 order_id）→ get_order_status 所有跨步骤的 ID（shop_id / cart_id / address_id / preview_id …）都由网关签发、原样回传，不要自行构造或跨链路混用。

下一步

MCP 工具

24 个外卖 MCP 工具的完整入参 / 出参

认证机制

API Key + consent grant 详解

下单链路

下单与支付时序全景

错误处理

统一错误码与处理

​1. 连接 MCP

​2. 用 MCP 工具下单

​完整链路一览

​下一步

MCP 工具

认证机制

下单链路

错误处理

1. 连接 MCP

2. 用 MCP 工具下单

完整链路一览

下一步