ZL-ClawPay

SKILL.md

---
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`。