构建 Agent - Clawdot虾点·文档中心

概述

本指南将带你使用 Clawdot Gateway，从零构建一个完整的本地生活 Agent。通过遵循最佳实践和处理边界情况，你将能够创建一个健壮、用户友好的应用。 Gateway 以 MCP（Model Context Protocol）工具的形式对外开放能力——你连上外卖 MCP，就能看到 24 个工具，用一串工具调用从绑定授权、找店选品，一路串到预览、下单、签约。本指南所有示例都以 工具名 + JSON 参数 给出（除绑定工具外，每个业务工具的参数都带 consent_grant_id）。

架构设计

一个完整的本地生活 Agent 由以下模块组成：

┌─────────────────────────────────────────────┐
│         用户交互层 (Agent 应用)              │
│  Claude Desktop / Kimi / 钉钉 / 自建 Agent   │
└────────────────────┬────────────────────────┘
                     │
┌────────────────────▼────────────────────────┐
│        业务逻辑层 (你的代码)                  │
│  • 用户授权管理      • 下单链路管理          │
│  • 本地缓存         • 错误处理               │
└────────────────────┬────────────────────────┘
                     │
┌────────────────────▼────────────────────────┐
│     Clawdot Gateway (MCP)                    │
│  • 商家搜索     • 订单预览 / 创建            │
│  • 菜单查询     • 免密签约                   │
│  • 地址管理     • 优惠券管理                │
└─────────────────────────────────────────────┘

外卖网关通过 Streamable HTTP 暴露 24 个 MCP 工具，覆盖从绑定授权到下单支付的完整本地生活能力。工具的连接方式、分组与下单顺序见 MCP 概览。

Step 1：获取 API Key 并连接 MCP

在控制台创建 Agent

访问 Clawdot 控制台，创建一个 Agent 并为它开通外卖能力。Agent 与 API Key 都在控制台管理。

复制 API Key

系统生成 API Key（clw_ 开头），仅显示一次，立即复制并保存到安全位置。服务端只存哈希，遗失需重新生成。

把 API Key 配进 MCP 客户端

网关以 Streamable HTTP（FastMCP）对外提供 MCP 服务，Endpoint 为 https://eleme-gateway.hicaspian.com/mcp/v1。把 API Key 配进你的 MCP 客户端连接头：

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

不要把 API Key 提交到 Git 仓库或硬编码进代码，用环境变量或密钥管理注入。

API Key 标识 Agent，在连接层通过 Authorization: Bearer clw_... 请求头传递，每个 MCP 请求都需要它。后续操作用户资源时，还需要下一步获取的用户授权（consent grant），它作为业务工具的参数 consent_grant_id 传入，不走请求头。详见认证机制。

Step 2：获取用户授权

操作用户资源（搜店、下单、查地址等）需要双层认证：连接层的 API Key 标识 Agent，用户授权（consent grant） 标识已授权的外卖用户。用户走一次绑定流程后，你拿到 consent_grant_id（cg_ 前缀），后续业务工具调用都把它作为参数带上。绑定支持两种模式：sms（向手机号下发验证码）与 h5（返回授权链接，用户在链接中登录授权）。绑定类工具 request_user_bind / verify_user_bind 是获取授权的入口，只需 Agent 身份（连接层 API Key），本身不传 consent_grant_id。下面以 sms 模式演示。

绑定流程

第一步，发起绑定，网关向用户手机下发验证码：

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

第二步，用户告知验证码后确认绑定，铸造 consent_grant_id：

// 工具：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（有效期约 300 秒），把链接交给用户打开完成授权；随后 verify_user_bind(auth_type="h5", request_id=...) 轮询，pending 表示还没好，bound=true 时返回 consent_grant_id。也可在 request_user_bind 传 callback_url，授权完成后网关 POST 回调（event=user_bind）。完整字段见发起绑定与确认绑定。

绑定成功返回的 expires_at 是授权过期时间（ISO 8601）。重授权即轮换：同一用户每次成功绑定都会铸造新的 consent_grant_id，旧的立即失效。授权可随时通过 revoke_user_bind 撤销，撤销后旧 consent_grant_id 即时失效。

Step 3：核心业务流程

实现从备好收货地址、搜店选品、算价、预览到下单的完整链路。整条链路是有状态的：每一步返回的 ID 必须原样回传给下一步，不可自造或跨链路混用。先备好收货地址、再按地址搜可送达的店，下游工具因此都拿得到配送坐标。

search_addresses → select_address → search_shops → get_shop_menu
            → quote_cart → preview_order → create_order

所有金额字段单位为分（整数），不是元。例如 payable_price: 1500 表示 ¥15.00。

免密支付签约是账户级的一次性前置（见下文「免密支付签约」），不属于每一单的链路、也不绑定某笔订单——不要把它当成下单链路里的一步。

下面每个业务工具调用都带 consent_grant_id 参数（来自 Step 2）。

Phase 1：准备收货地址

先定下”送到哪里”。地址流程 = 搜 POI 拿一次性 token → 登记拿 address_id。先搜地址：

// 工具：search_addresses —— 搜地址 POI，拿建议（含一次性 token）
{
  "consent_grant_id": "cg_your_consent_grant",
  "keyword": "光谷世界城",
  "lat": 30.5,
  "lng": 114.4
}
// → { "saved_addresses": [ { "address_id": "...", ... } ], "suggestions": [ { "token": "...", ... } ] }

saved_addresses[] 是已保存地址，可直接复用其 address_id；新地址则取一条 suggestions[].token，作为 select_address 的 suggestion_token 入参登记：

// 工具：select_address —— 用 suggestion_token 登记/选择地址，拿 address_id
{
  "consent_grant_id": "cg_your_consent_grant",
  "suggestion_token": "<上一步 suggestion_token>",
  "contact_name": "张三",
  "contact_phone": "13800138000",
  "address_detail": "3 号楼 101"
}
// → { "address_id": "...", "display_name": "...", "lat": ..., "lng": ... }

也可直接用已有地址的 address_id 调 select_address。这个 address_id 既用于下一步搜店，也用于后续算价 / 预览。详见搜索地址与选择/登记地址；编辑门牌 / 标签用 update_address（address_id 不变）。

Phase 2：搜索商家

// 工具：search_shops —— 按收货地址搜索 / 浏览可送达商家
{
  "consent_grant_id": "cg_your_consent_grant",
  "address_id": "<来自上一步选址>",
  "keyword": "生椰拿铁"
}
// → { "shops": [ { "shop_id": "...", "cart_id": "...", "name": "...", "rating": ..., "min_order_amount": ... } ], "next_offset": ... }

用上一步的 address_id 搜可送达的店铺。不传 keyword 即按该地址附近浏览模式（最多 20 家），带距离、评分、配送费、起送价等决策字段；传 keyword（店名 / 品类 / 商品名）则精确搜索（约 5 家）。浏览模式可传 offset 翻页：首次传 offset: 0，用返回的 next_offset 继续翻，直到 shops 为空。每个结果都附带 shop_id 与 cart_id：cart_id 已封装该店铺与本次配送坐标，是后续 get_shop_menu / quote_cart / preview_order 的入口，原样回传即可，下游工具因此免传经纬度。完整字段见搜索店铺。

Phase 3：查看菜单详情

// 工具：get_shop_menu —— 获取商家菜单
{
  "consent_grant_id": "cg_your_consent_grant",
  "shop_id": "<来自搜索>",
  "cart_id": "<来自搜索>",
  "keyword": "拿铁"
}
// → { "categories": [...], "items": [ { "item_id": "...", "sku_id": "...", "ingredient_options": [...] } ], "has_more": false }

菜单可能很大（100+ 项），可用 keyword 或 limit / offset 渐进披露，按 has_more 判断是否还有更多。下单必须使用 get_shop_menu 返回的 item_id / sku_id（以及规格 / 加料的 ingredient_option_ids）。完整字段见店铺菜单；规格 / 属性 / 加料体系见商品规格说明。

Phase 4：购物车算价

// 工具：quote_cart —— 购物车算价，拿 quote_id
{
  "consent_grant_id": "cg_your_consent_grant",
  "shop_id": "<来自搜索>",
  "cart_id": "<来自搜索>",
  "address_id": "<来自选址>",
  "items": [
    {"item_id": "item_001", "sku_id": "sku_001", "quantity": 2, "ingredient_option_ids": []},
    {"item_id": "item_002", "sku_id": "sku_002", "quantity": 1, "ingredient_option_ids": []}
  ]
}
// → { "quote_id": "...", "can_checkout": true, "payable_price": 1500 }

items 是一个数组（不是 JSON 字符串），每项的 item_id / sku_id 来自 get_shop_menu。can_checkout 指示是否满足起送等下单条件，payable_price 是预估应付（单位分）。完整字段见购物车算价。

Phase 5：预览订单（下单前确认）

始终在创建订单前用 preview_order 校验并向用户确认最终价格，避免误操作。预览产出的 preview_id + confirmation_token 是真正下单所需的凭据。

// 工具：preview_order —— 预览订单，拿 preview_id + confirmation_token
{
  "consent_grant_id": "cg_your_consent_grant",
  "shop_id": "<来自搜索>",
  "cart_id": "<来自搜索>",
  "address_id": "<来自选址>",
  "items": [
    {"item_id": "item_001", "sku_id": "sku_001", "quantity": 2, "ingredient_option_ids": []}
  ],
  "quote_id": "<来自算价>",
  "order_remark": "放门口，请按门铃"
}
// → { "preview_id": "prv_...", "confirmation_token": "cf_...", "price": {...}, "available_coupons": [...] }

preview_id + confirmation_token 须配对使用，由同一次预览产出，有效期约 10 分钟。 优惠券在预览阶段生效，当前订单可用券以返回的 available_coupons 为准（coupon_ids 三态：不传=自动选最优券；[]=不用券；["<coupon_id>"]=指定券）。要换券时，选中 available_coupons[].coupon_id，带 coupon_ids=[...] 重新调一次 preview_order 重算：

// 工具：preview_order —— 选券后重算
{
  "consent_grant_id": "cg_your_consent_grant",
  "shop_id": "<来自搜索>",
  "cart_id": "<来自搜索>",
  "address_id": "<来自选址>",
  "items": [
    {"item_id": "item_001", "sku_id": "sku_001", "quantity": 2, "ingredient_option_ids": []}
  ],
  "coupon_ids": ["<选中的 coupon_id>"]
}
// → { "preview_id": "prv_...", "confirmation_token": "cf_...", "price": {...}, "selected_coupons": [...] }

账户级券列表可用 list_coupons 查看，但当前订单实际可用以 preview_order 的 available_coupons 为准。完整字段与 coupon_ids 三态说明见预览订单。

Phase 6：创建订单

用同一次预览的 preview_id + confirmation_token 正式下单：

// 工具：create_order —— 创建订单（confirmation_token 即幂等键）
{
  "consent_grant_id": "cg_your_consent_grant",
  "preview_id": "prv_...",
  "confirmation_token": "cf_...",
  "callback_url": "https://your.app/callbacks/order"
}
// → { "order_id": "ord_...", "status": "...", "payment_action": {...} }

本工具以 confirmation_token 为幂等键：同一令牌只能下一单，再次下单需重新预览取新令牌。返回 order_id、status 与（需支付时的）payment_action。可选传 callback_url，这笔单每次状态变化都会 POST 一条回调（体含 order_id、seq、status 等；支付结果那条为 event=order_payment 并带 ispay）；不传则自行用 get_order_status 轮询。完整字段见创建订单。

Step 4：免密支付签约（账户级，一次性）

免密签约让用户授权免密支付：签约一次，后续免密支付类订单即可自动扣款。它是账户级、一次性的前置设置，不绑定某一笔订单、也不是每单都要做——所以独立于上面的下单链路。建议在需要免密支付前先用 get_sign_status 查是否已签约，未签约再发起：

// 工具：get_sign_action —— 发起免密签约（拿 H5 签约动作）
{
  "consent_grant_id": "cg_your_consent_grant",
  "return_url": "https://your.app/sign/callback"
}
// → 免密签约动作：action_type=open_h5 时含 action_url（H5 签约页）；none 表示已签约

action_type=open_h5 时把用户引导到 action_url（H5 签约页）完成签约，完成后浏览器跳回 return_url；none 表示已签约。随后用 get_sign_status 轮询签约结果：

// 工具：get_sign_status —— 查询签约状态
{
  "consent_grant_id": "cg_your_consent_grant"
}
// → { "signed": ..., "status": "...", ... }

完整字段见发起免密签约与查询签约状态；下单链路与支付时序见下单流程。

Step 5：处理边界情况

健壮的 Agent 应该优雅地处理各种边界情况，提供友好的错误提示。Gateway 的错误统一返回 {"error": {"code", "message"}} 结构（每个 MCP 工具失败时都是这个形状）。

错误处理

按 error.code 分支给用户友好提示：

错误码	含义	建议处理
`AUTH_REQUIRED` / `AUTH_INVALID`	连接层 API Key 缺失或无效	检查 `Authorization: Bearer clw_...` 连接头
`CONSENT_GRANT_INVALID` / `CONSENT_GRANT_EXPIRED`	用户授权无效或已过期	重新发起绑定（`request_user_bind` → `verify_user_bind`）
`CAP_NOT_BOUND`	当前 Agent 未开通该能力	在控制台为 Agent 开通对应能力
`PUBLIC_REFERENCE_INVALID`	平台 ID（店铺 / 地址 / 订单）无效、过期或不属于当前用户	重新从上一步获取该 ID，不要自造或跨链路混用
`RATE_LIMITED` / `QUOTA_EXCEEDED`	请求过于频繁或配额用尽	用指数退避稍后重试
`ELEME_ERROR`	上游服务异常	提示用户稍后重试，或降级展示缓存结果

# 示意：包装一次 MCP 工具调用，按 error.code 分支处理
def handle_tool_result(result: dict):
    err = result.get("error")
    if not err:
        return result  # 成功，直接用
    code = err["code"]
    if code in ("AUTH_REQUIRED", "AUTH_INVALID"):
        print("❌ 连接层 API Key 缺失或无效，请检查 Authorization 头")
    elif code in ("CONSENT_GRANT_INVALID", "CONSENT_GRANT_EXPIRED"):
        print("❌ 用户授权无效或已过期，请重新发起绑定")
    elif code == "CAP_NOT_BOUND":
        print("❌ 当前 Agent 未开通该能力，请在控制台开通")
    elif code == "PUBLIC_REFERENCE_INVALID":
        print("❌ 平台 ID（店铺 / 地址 / 订单）无效、过期或不属于当前用户")
    elif code in ("RATE_LIMITED", "QUOTA_EXCEEDED"):
        print("❌ 请求过于频繁或配额用尽，请稍后再试")
    elif code == "ELEME_ERROR":
        print("❌ 上游服务异常，请稍后重试")
    else:
        print(f"❌ 工具错误：{code} - {err.get('message')}")
    return None

用户授权过期处理

任意业务工具返回 CONSENT_GRANT_INVALID / CONSENT_GRANT_EXPIRED 即表示需要重新授权（也可主动比对绑定时记录的 expires_at）。重新走一遍绑定流程即可——重授权即轮换，会得到新的 consent_grant_id，把它替换掉本地存储的旧值。

业务工具返回 CONSENT_GRANT_INVALID / EXPIRED
  → request_user_bind（拿 bind_id，用户收验证码）
  → verify_user_bind（拿新的 consent_grant_id）
  → 用新 consent_grant_id 重试原工具调用

商家关闭处理

search_shops 浏览模式结果中的 available / unavailable_reason 可提前判断商家是否营业。若下单链路中途遇到商家关闭，提示用户选择其他商家，并回到 search_shops 重新选店。

订单查询重试

get_order_status 是只读查询，超时可安全重试：

// 工具：get_order_status —— 查询订单（只读，可重试）
{
  "consent_grant_id": "cg_your_consent_grant",
  "order_id": "ord_..."
}
// → { "status": "...", "status_text": "...", "paid_at": ..., "delivery": {...} }

建议对 get_order_status 这类只读工具做有上限的退避重试（如最多 3 次），下单类工具则不要盲目重试——靠 confirmation_token 幂等键避免重复下单。

最佳实践

复用已保存地址

search_addresses 返回 saved_addresses[]，优先复用其 address_id，避免重复登记新地址。

// search_addresses 返回里取
// saved_addresses[0].address_id 直接喂给后续工具

渐进披露大菜单

菜单可能有 100+ 项。get_shop_menu 用 keyword 或 limit / offset 分页，按 has_more / next_offset 翻页直到取完。

// 工具：get_shop_menu
{"consent_grant_id": "cg_...", "shop_id": "...", "cart_id": "...", "keyword": "拿铁"}

日志和监控

记录关键工具调用（入参摘要、返回的 order_id / 错误码等），便于调试和监控。注意脱敏 consent_grant_id 等敏感字段。

速率限制处理

尊重速率限制（下单 10 次/分钟，其他 60 次/分钟，每 Agent）。超限时工具返回 RATE_LIMITED，用指数退避重试。

金额单位统一为分

所有金额字段都是分（整数）。展示给用户时除以 100，不要把分当元。payable_price: 1500 即 ¥15.00。

优雅降级

当上游不可用（ELEME_ERROR）时，提供替代方案（展示缓存结果或提示用户稍后重试）。

完整链路一览

把上面各步骤的工具调用串起来，就是一次完整下单：

request_user_bind / verify_user_bind  → consent_grant_id
search_addresses → 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（address_id / shop_id / cart_id / preview_id / confirmation_token …）都由网关签发、原样回传，不要自行构造或跨链路混用。confirmation_token 是下单幂等键，绑定阶段铸造的 consent_grant_id 是后续每个业务工具调用都要带的用户授权参数。免密支付签约（get_sign_action）是账户级、一次性的前置，独立于这条下单链路（见 Step 4）。

下一步

查看 MCP 概览了解 24 个工具的连接方式、分组与完整入参 / 出参
阅读下单流程掌握完整的有状态下单链路与支付时序
阅读安全模型学习数据保护最佳实践
探索支持的平台集成到你的 Agent 应用

​概述

​架构设计

​Step 1：获取 API Key 并连接 MCP

​Step 2：获取用户授权

​绑定流程

​Step 3：核心业务流程

​Phase 1：准备收货地址

​Phase 2：搜索商家

​Phase 3：查看菜单详情

​Phase 4：购物车算价

​Phase 5：预览订单（下单前确认）

​Phase 6：创建订单

​Step 4：免密支付签约（账户级，一次性）

​Step 5：处理边界情况

​错误处理

​用户授权过期处理

​商家关闭处理

​订单查询重试

​最佳实践

复用已保存地址

渐进披露大菜单

日志和监控

速率限制处理

金额单位统一为分

优雅降级

​完整链路一览

​下一步

概述

架构设计

Step 1：获取 API Key 并连接 MCP

Step 2：获取用户授权

绑定流程

Step 3：核心业务流程

Phase 1：准备收货地址

Phase 2：搜索商家

Phase 3：查看菜单详情

Phase 4：购物车算价

Phase 5：预览订单（下单前确认）

Phase 6：创建订单

Step 4：免密支付签约（账户级，一次性）

Step 5：处理边界情况

错误处理

用户授权过期处理

商家关闭处理

订单查询重试

最佳实践

完整链路一览

下一步