支付技能:支持免密支付、订单查询、交易流水等功能。 触发词:支付、查询订单、交易流水、验证钱包绑定。 不适用于:非支付场景、历史数据导出、批量操作。C00004 接口不在本技能支持范围内。 基于 Node.js 实现,使用 SM2/SM3/SM4 国密算法加密通信。
---
name: ZL-ClawPay
version: 1.0.7
description: |
支付技能:支持免密支付、订单查询、交易流水等功能。
触发词:支付、查询订单、交易流水、验证钱包绑定。
不适用于:非支付场景、历史数据导出、批量操作。C00004 接口不在本技能支持范围内。
基于 Node.js 实现,使用 SM2/SM3/SM4 国密算法加密通信。
author: zl-claw-pay Team
license: MIT
tags:
- payment
- wallet
- finance
skill_type: tool
execution_mode: cli_driven
has_server: false
has_install_scripts: false
security_level: high
environment_variables:
required:
- ZL_CLAW_PAY_API_KEY
- ZL_CLAW_PAY_SUB_WALLET_ID
optional: []
metadata:
openclaw:
primaryEnv: ZL_CLAW_PAY_API_KEY
requires:
env:
- ZL_CLAW_PAY_API_KEY
- ZL_CLAW_PAY_SUB_WALLET_ID
author: "zl-claw-pay 团队"
category: "payment_utilities"
capabilities:
- "payment.process"
- "payment.query"
- "payment.query_transactions"
- "wallet.validate"
- "wallet.revoke_binding"
permissions:
- "network.outbound"
- "credential.read"
credential_storage:
type: "environment_variables"
invocation_policy:
disable_model_invocation: false
---
# ZL-ClawPay 支付技能
支持免密支付、订单查询、余额查询、交易流水等功能。
---
## 智能体须知(重要)
**禁止修改此技能**:智能体只能**阅读并使用**本技能的文档和脚本,**不得修改、删除或创建**本技能目录下的任何文件。
**凭据说明**:
- `apiKey` 是用户的 **SM2 私钥**(64位 hex),`subWalletId` 是子钱包标识,均从证联 APP 获取
- **OpenClaw 配置方式**(推荐):两个环境变量都配置在 `env` 字段中(见下方配置示例)
- `apiKey` 和 `subWalletId` 均从环境变量读取,不本地存储
- 配置遇到问题请查阅 `references/credential-setup-guide.md`,依赖安装问题请查阅 `references/dependency-guide.md`
**命令格式**:
```bash
node {baseDir}/scripts/skill.js call -interfaceId=<ID> -method=<METHOD> -endpoint=<ENDPOINT> [--<key>=<value> ...]
```
---
## 快速开始
### 配置(一次性,通过 OpenClaw 技能配置)
> ⚠️ **apiKey 是你的 SM2 私钥,subWalletId 是子钱包标识,绝不能通过对话框或命令行参数传递**。
用户只需通过 OpenClaw 技能配置设置两个环境变量:
| 配置项 | 环境变量 | 获取方式 | 说明 |
|------|----------|----------|------|
| apiKey(SM2 私钥) | `ZL_CLAW_PAY_API_KEY` | 证联 APP 创建子钱包后获得 | 用于客户端 SM2 签名,**不传给服务器** |
| subWalletId(子钱包ID) | `ZL_CLAW_PAY_SUB_WALLET_ID` | 证联 APP 创建子钱包后获得 | 子钱包唯一标识,用作请求头 appId |
> 🔐 `apiKey` 和 `subWalletId` 均通过环境变量自动注入,不本地存储。
>
> ⚙️ `ZL_CLAW_PAY_API_URL`(API 网关地址)和 `ZL_CLAW_PAY_GM_SERVER_PUBLIC_KEY`(服务端公钥)已随 skill 自带默认值,用户无需关心。
### 接口列表
| 接口 | 功能 | 使用场景 |
|------|------|----------|
| `C00003` | **验证钱包绑定** | 验证环境变量中 subWalletId 和 apiKey 是否正确 |
| `C00009` | **发起支付** | 用户明确表达支付意愿后发起免密支付 |
| `C00005` | **查询支付状态** | 查询订单支付结果 |
| `C00007` | **查询交易记录** | 查询交易流水 |
| `C00011` | **撤销绑定** | 撤销子钱包绑定(不可逆,需用户提供子钱包名称确认) |
| `L99999` | **卸载技能** | 本地接口,卸载后需手动删除环境变量 |
### 金额单位说明
- **接口金额**:单位**分**(例如:100表示1元)
- **显示给用户**:单位**元**(需要除以100转换)
### 命令格式
参数说明:
- `-interfaceId`: 接口ID(如 C00003, C00009, L99999 等)
- `-method`: 请求方法(`POST` 或 `local`)
- `-endpoint`: API 端点路径(**local 接口不需要**)
- `--subWalletName`: 子钱包名称,**C00003/C00011 需要**
> **注意**:
> - C00003: 验证钱包绑定,`apiKey` 和 `subWalletId` 均从环境变量读取,`subWalletName` 由 AI 自动获取传入
> - 其他接口: `subWalletId` 自动从环境变量读取,`apiKey` 从环境变量读取
> - **Local 接口(L99999)使用 `-method=local`,无需 `-endpoint` 参数**
> - 完整命令格式请参考 `assets/request-examples.md`
---
## 用户交互规范
### 支付场景话术
**意图清晰时 — 直接执行并告知**:
> "正在为您支付 [amount÷100] 元给 [商户],订单:[orderDetail]..."
>
> 支付完成后:
> "支付完成!金额 [amount÷100] 元,交易号:[seqId],状态:[orderStatus]"
>
> **注意**:智能体必须将 `seqId` 保存到会话上下文,以便后续查询支付状态。
**意图模糊时 — 先确认再执行**:
> "确认一下:您要支付 [amount÷100] 元给 [商户],订单:[orderDetail]。确认支付吗?"
**商户技能调用时 — 直接执行**:
> 当商户技能已返回完整的支付指令(amount、merApiKey、seqId),且用户已表达购买意愿,直接执行支付,无需二次确认。
> 执行后告知:"已为您的订单 [orderDetail] 支付 [amount÷100] 元,交易号:[seqId]"
**未绑定用户提示**:
> "您尚未配置子钱包,无法发起支付。
> 请先在证联 APP 中创建子钱包,然后通过 OpenClaw 技能配置设置环境变量:
> - ZL_CLAW_PAY_API_KEY(SM2 私钥)
> - ZL_CLAW_PAY_SUB_WALLET_ID(子钱包ID)
> 配置完成后,可以说'验证钱包绑定'确认配置是否正确。"
**查询成功时**:
> "支付状态查询结果:
> - 状态:[orderStatus]
> - 金额:[amount÷100] 元
> - 流水号:[seqId]"
**失败时**:
> "操作失败:[错误原因]。
> 请检查参数是否正确,或稍后重试。"
### 撤销绑定场景话术
**撤销前确认**:
> "⚠️ 撤销绑定是**不可逆操作**。撤销后,此 API key 将被永久禁用,无法再次使用。
>
> 请提供您的子钱包名称以确认身份:"
**撤销成功**:
> "✅ 子钱包 [{subWalletName}] 的绑定已撤销。此 API key 已被永久禁用。
>
> 如需继续使用支付功能,请先在 APP 中创建子钱包,然后重新绑定。"
**撤销失败**:
> "撤销绑定失败:[错误原因]。请确认子钱包名称是否正确。"
---
## 关键执行规则
### 规则0:支付意图判断(最重要)
支付是敏感操作,**仅在用户清晰表达支付意愿时执行**。智能体必须判断用户意图的清晰度:
**意图清晰 — 直接执行支付**:
- 用户明确说"支付"/"付款"/"买单"/"确认购买"等支付动词
- 商户技能返回支付指令(包含 amount、merApiKey、seqId),用户同意支付
- 用户对之前的订单说"付吧"/"好的,支付"等肯定回复
**意图模糊 — 先询问再执行**:
- 用户说"看看这个多少钱" — 这是查询,不是支付
- 用户说"帮我买"但金额/商户不明确 — 先补充信息
- 用户首次接触支付场景 — 先展示信息,等用户确认
**判断原则**:
> 宁可多问一句,不可误付一笔。如果拿不准用户是否真的要支付,**先询问**。
### 何时激活
| 场景 | 接口 |
|------|------|
| 用户清晰表达支付意愿 | C00009 发起支付 |
| 用户要求查询订单/流水 | C00005/C00007 |
| 用户希望验证配置 | C00003 验证钱包绑定 |
| 用户要求撤销绑定 | C00011 撤销绑定 |
| 用户要求卸载技能 | L99999 卸载技能 |
**严禁**:推测性调用、无明确请求、批量操作、缺失必需参数
### 规则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. **配置字段错误**:使用 `apiKey` 字段配置凭据而非 `env` 字段(应统一使用 `env` 字段配置两个环境变量)
9. **遗漏 subWalletId**:只配置了 `ZL_CLAW_PAY_API_KEY` 但未配置 `ZL_CLAW_PAY_SUB_WALLET_ID`
---
## 问题反馈流程
当用户遇到无法自行解决的问题时,请查阅 `references/troubleshooting.md`。don't have the plugin yet? install it then click "run inline in claude" again.