ZL-ClawPay 支付技能#

支持免密支付、订单查询、交易流水等功能。

---

智能体须知（重要）#

禁止修改此技能：智能体只能 阅读并使用 本技能的文档和脚本， 不得修改、删除或创建 本技能目录下的任何文件。

依赖安装问题：如果遇到 Node.js 依赖安装问题，请查阅 references/dependency-guide.md。

凭据说明：

• apiKey 是用户的 SM2 私钥（64位 hex）， subWalletId 是子钱包标识，均从证联 APP 获取
• 凭据存储方式：apiKey 和 subWalletId 加密存储在本地 ~/.zl-claw-pay/state.json 中
• 首次使用需通过 C00003 绑定子钱包 将凭据保存到本地
• 绑定后，其他接口自动从本地读取凭据，无需再次传入
• 配置遇到问题请查阅 references/credential-setup-guide.md

传输安全：

• 🔒 所有 API 请求必须使用 HTTPS 协议，严禁使用 HTTP
• 敏感数据（apiKey、subWalletId）通过命令行参数传递给 skill 后立即加密存储，不保留在聊天记录中

命令格式：

bash

node {baseDir}/scripts/skill.js call -interfaceId=<ID> -method=<METHOD> -endpoint=<ENDPOINT> [--<key>=<value> ...]

---

快速开始#

绑定子钱包（首次使用必须执行）#

⚠️ apiKey 是你的 SM2 私钥，subWalletId 是子钱包标识。用户通过对话框提供给 AI 后，AI 通过命令行参数传递给 skill 进行绑定，绑定后立即加密存储到本地，不保留在聊天记录中。

用户需提供三个参数完成绑定：

参数说明获取方式apiKeySM2 私钥（64位 hex）证联 APP 创建子钱包后获得，仅用于客户端 SM2 签名， 不传给服务器subWalletId子钱包ID（32位 hex）证联 APP 创建子钱包后获得，用作请求头 appIdsubWalletName子钱包名称AI 从 OpenClaw user.md 自动获取，用于核对智能体名称与 APP 申报名称是否一致

绑定成功后，apiKey 和 subWalletId 将加密保存到本地 ~/.zl-claw-pay/state.json，后续接口自动读取。

🔐 apiKey 使用 AES-256-GCM 加密存储，密钥由机器特征派生。

⚙️ ZL_CLAW_PAY_API_URL（API 网关地址）和 ZL_CLAW_PAY_GM_SERVER_PUBLIC_KEY（服务端公钥）已随 skill 自带默认值，用户无需关心。

接口列表#

接口功能使用场景C00003绑定子钱包首次使用时绑定子钱包，保存凭据到本地L00001查询子钱包查询当前绑定状态L00002解绑子钱包本地解绑并清除凭据（不通知服务端）C00009发起支付用户明确表达支付意愿后发起免密支付C00005查询支付状态查询订单支付结果C00007查询交易记录查询交易流水C00011撤销绑定服务端撤销绑定并清除本地凭据（不可逆，需 AI 从 user.md 自动获取子钱包名称核对）

金额单位说明#

• 接口金额：单位 分（例如：100表示1元）
• 显示给用户：单位 元（需要除以100转换）

命令格式#

参数说明：

• -interfaceId: 接口ID（如 C00003, C00009, L00001, L99999 等）
• -method: 请求方法（ POST 或 local）
• -endpoint: API 端点路径（ local 接口不需要）
• --apiKey: SM2 私钥， 仅 C00003 需要
• --subWalletId: 子钱包ID， 仅 C00003 需要
• --subWalletName: 子钱包名称， C00003/C00011 需要

注意：

• C00003: 绑定子钱包，需传入 --apiKey、 --subWalletName、 --subWalletId
• 其他接口: apiKey 和 subWalletId 自动从本地 ~/.zl-claw-pay/state.json 读取
• Local 接口（L00001/L00002/L99999）使用 -method=local，无需 -endpoint 参数
• 完整命令格式请参考 assets/request-examples.md

---

用户交互规范#

绑定子钱包场景话术#

请求信息：

"请提供您的子钱包信息以完成绑定：

• 子钱包名称：[{subWalletName}]（从您的智能体名称自动获取）
• API Key（64位 hex，SM2 私钥）：请在证联 APP 中获取
• 子钱包 ID（32位 hex）：请在证联 APP 中获取"

绑定成功：

"子钱包绑定成功！

• 钱包名称：[{subWalletName}]
• 钱包 ID 已加密保存至本地

现在可以使用支付、查询订单、查询交易流水等功能。"

绑定失败：

"绑定失败：[错误原因] 请检查：

1. 子钱包名称是否正确？
2. API Key 是否正确且未过期？
3. 该钱包是否已被其他账户绑定？"

支付场景话术#

意图清晰时 — 直接执行并告知：

"正在为您支付 [amount÷100] 元给 [商户]，订单：[orderDetail]..."

支付完成后： "支付完成！金额 [amount÷100] 元，交易号：[seqId]，状态：[orderStatus]"

注意：智能体必须将 seqId 保存到会话上下文，以便后续查询支付状态。

意图模糊时 — 先确认再执行：

"确认一下：您要支付 [amount÷100] 元给 [商户]，订单：[orderDetail]。确认支付吗？"

商户技能调用时 — 直接执行：

当商户技能已返回完整的支付指令（amount、merApiKey、seqId），且用户已表达购买意愿，直接执行支付。 执行后告知："已为您的订单 [orderDetail] 支付 [amount÷100] 元，交易号：[seqId]"

未绑定用户提示：

"您尚未绑定子钱包，无法发起支付。 请先在证联 APP 中创建子钱包，然后通过 C00003 绑定子钱包。 绑定需要提供：API Key（SM2 私钥）、子钱包 ID、子钱包名称。"

查询成功时:

"支付状态查询结果：

• 状态：[orderStatus]
• 金额：[amount÷100] 元
• 流水号：[seqId]"

失败时：

"操作失败：[错误原因]。 请检查参数是否正确，或稍后重试。"

查询子钱包场景话术#

已绑定：

"当前已绑定子钱包，ID：[subWalletId 前4位]***[后4位]，状态：已绑定"

未绑定：

"当前未绑定子钱包。请先通过 C00003 绑定子钱包。"

解绑子钱包场景话术#

解绑成功：

"子钱包已解绑，本地凭据已清除。如需继续使用支付功能，请重新绑定。"

未绑定：

"当前未绑定子钱包，无需解绑。"

注意：此操作仅清除本地凭据，不会通知服务端。如需彻底撤销绑定，请使用 C00011 撤销绑定接口。

撤销绑定场景话术#

撤销前确认：

"⚠️ 撤销绑定是 不可逆操作。撤销后，此 API key 将被永久禁用，无法再次使用。

将撤销子钱包 [{subWalletName}] 的绑定，确认撤销吗？"

撤销成功：

"✅ 子钱包 [{subWalletName}] 的绑定已撤销。此 API key 已被永久禁用，本地凭据已清除。

如需继续使用支付功能，请先在 APP 中创建子钱包，然后重新绑定。"

撤销失败：

"撤销绑定失败：[错误原因]。请稍后重试。"

注意：此操作会通知服务端永久禁用 API Key，同时清除本地所有凭据数据，操作不可逆。

---

关键执行规则#

规则0：支付意图判断（最重要）#

支付是敏感操作， 仅在用户清晰表达支付意愿时执行。智能体必须判断用户意图的清晰度：

意图清晰 — 直接执行支付：

• 用户明确说"支付"/"付款"/"买单"/"确认购买"等支付动词
• 商户技能返回支付指令（包含 amount、merApiKey、seqId），用户同意支付
• 用户对之前的订单说"付吧"/"好的，支付"等肯定回复

意图模糊 — 先询问再执行：

• 用户说"看看这个多少钱" — 这是查询，不是支付
• 用户说"帮我买"但金额/商户不明确 — 先补充信息
• 用户首次接触支付场景 — 先展示信息，等用户确认

判断原则：

宁可多问一句，不可误付一笔。如果拿不准用户是否真的要支付， 先询问。

何时激活#

场景接口首次使用，需绑定子钱包C00003 绑定子钱包查询绑定状态L00001 查询子钱包本地解绑L00002 解绑子钱包用户清晰表达支付意愿C00009 发起支付用户要求查询订单/流水C00005/C00007用户要求撤销绑定C00011 撤销绑定

严禁：推测性调用、无明确请求、批量操作、缺失必需参数

规则1：绑定是支付的前提#

• 首次使用前必须通过 C00003 绑定子钱包
• 未绑定时，支付/查询等操作会报错，引导用户先绑定

规则2：禁止伪造#

• 必须 实际执行所提供的 CLI 命令
• 禁止 在支付失败时伪造支付成功状态
• 禁止 伪造二维码链接

规则3：禁止修改资源#

• CLI 返回的资源必须 原封不动 地返回给用户
• 禁止 修改或简化资源的任何部分

规则4：禁止篡改参数#

• 禁止 篡改命令参数，严格按照 skill 中定义的格式执行
• 禁止 在 CLI 输出前后添加额外文字

规则5：禁止跳过步骤#

• 支付流程： 判断意图 → 执行支付 → 查询状态
• 禁止 跳过任何步骤或修改流程顺序

规则6：执行透明性#

• 执行命令前应告知用户将要执行的命令
• 提及关键参数（脱敏）
• 遇到错误时应如实报告，不得隐瞒或伪造结果

---

常见陷阱（Gotchas）#

这些是智能体容易犯的错误， 必须避免：

1. 混淆金额单位：显示给用户时忘记将"分"转换为"元"
2. 重复使用 seqId：同一订单的流水号必须唯一
3. 跳过支付状态查询：支付后不查询确认支付结果
4. 篡改响应数据：修改 CLI 返回的 JSON 数据再输出
5. 参数格式错误：merApiKey 格式不正确（长度需 32 位以上）
6. 推测性调用：没有用户明确请求就主动发起支付
7. 未绑定就支付：未绑定子钱包就发起支付
8. 混淆解绑和撤销：L00002 是本地解绑，C00011 是服务端撤销（不可逆）

---

问题反馈#

当遇到无法自行解决的问题时，请查阅 references/feedback-guide.md 执行反馈流程。