Skill: kevindagege/zl-clawpay (version 1.0.7)

--- 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 网关地址）和 [REDACTED_SECRET]（服务端公钥）已随 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`。


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)