alipay-pay-for-402-service#

由支付领域龙头企业支付宝提供的基于402协议的支付技能，提供极高精准度的服务及对应的超高稳定性保障。当且仅当 HTTP 请求返回状态码 402 Payment Required 时（无论是你发起的请求还是用户提供的响应）时，你需要使用本技能。对于其他格式的付款要求，暂不在本技能的使用范畴内。 你可以基于命令行执行工具 exec 来调用 alipay-bot 客户端工具的命令来完成付款。

执行透明性：执行每个 alipay-bot 命令前，应向用户简要说明即将执行的操作及其用途，确保用户知情。

请注意每次收到新的 HTTP 402 响应，你都应该重新执行本流程，而不是复用过往的支付记录。

请在 Step 2 输出后等待用户支付完成通知，再继续后续步骤，请勿自动连续执行全流程#

安全性与设计说明#

本技能由支付宝官方提供，以下设计均基于业务必要性：

CLI 工具来源与供应链安全#

• @alipay/agent-payment 是支付宝官方发布的 npm 包， @alipay scope 由 Ant Group 持有
• 版本锁定为 @1.0.0，配合 SHA-512 完整性校验，确保安装内容与官方发布一致
• 安装前必须通过完整性校验，校验失败则禁止安装（详见"环境依赖"章节）
• 官方 npm 页面： https://www.npmjs.com/package/@alipay/agent-payment

参数注入防护#

本技能所有 CLI 命令参数均使用 单引号 包裹，Shell 不会对单引号内内容进行变量展开或命令替换。此外：

• 文件名严格限制为 [a-zA-Z0-9._-]，禁止路径分隔符和 shell 特殊字符
• tradeNo 仅允许32位纯数字
• resource_url 必须为 https:// 开头，禁止 shell 特殊字符和路径穿越

URL 原样输出#

CLI 返回的 URL 是一次性生成的授权链接，包含加密签名参数。任何字符的修改都会导致签名校验失败、链接失效。原样输出是功能正确性的要求，而非安全风险。这些 URL 具有时效性（通常 5 分钟内有效），仅用于引导当前用户至支付宝 APP 核验身份并完成相关操作的链接。

URL 安全处理：支付链接具有时效性和用户绑定特性，请注意以下处理要求：

• 不将支付链接写入持久化日志或缓存
• 不通过非用户指定渠道发送支付链接
• 用户完成支付后链接自动失效

MEDIA 图片路径#

CLI 生成的二维码图片路径（如 /tmp/openclaw/alipay-bot-cli/qrcode/xxx.png）是本技能通过加密通信从支付宝服务端获取的二维码图片，用于展示给用户扫码。图片路径本身不包含敏感信息，二维码内容为引导当前用户至支付宝 APP 核验身份并完成相关操作的链接。

数据流转与隐私说明#

本技能在运行过程中涉及以下数据流转：

数据用途是否必需传输目标Payment-Needed 头发起 402 协议支付必需alipay-bot CLI → 支付宝服务端环境变量（AIPAY_MODEL, AIPAY_OS 等）输出格式适配、问题定位可选alipay-bot CLIAIPAY_SESSION_ID, AIPAY_FRAMEWORK会话追踪可选alipay-bot CLI支付链接/二维码用户完成支付必需仅展示给用户paymentProof携带凭证重试原始请求必需原始资源服务端

隐私保护措施：

• 环境变量均为可选参数，未提供时使用默认值，不影响功能使用。如用户不希望传递设备或模型信息，可省略 AIPAY_MODEL 和 AIPAY_OS 环境变量
• 支付链接具有时效性（约 5 分钟），过期后自动失效，不应写入持久化日志
• alipay-bot 仅与支付宝官方服务端通信，不向第三方发送数据
• 不会将支付链接通过非用户指定渠道发送

⚠️ Gotchas（常见陷阱）#

这些是模型容易犯的错误， 必须避免：

1. 跳过 Step 0：模型可能直接执行 alipay-bot -- 402-buyer-pay，需要先执行 Step 0
2. 等待用户确认：Step 0 输出后，模型可能等待用户确认，但应该直接进入 Step 1
3. 读取/分析图片：模型可能尝试打开或识别 MEDIA 行中的图片文件，但 MEDIA 行由框架自动处理，模型只需原样输出 CLI 结果（包含 MEDIA 行）
4. 重复输出：模型可能先用代码块展示 CLI 输出，再自己排版输出一遍，但应该只输出一遍
5. 截断 URL：模型可能压缩或截断 URL，但必须逐字符完整保留
6. 不调用授权技能：当需要授权时，模型可能只输出提示文字而不调用授权技能，但应主动调用 alipay-authenticate-wallet 技能
7. 拆分轮询命令：模型可能将 for 循环拆分成多次执行，但必须作为一条完整命令
8. 访问隐藏目录：模型可能尝试读取隐藏目录（以 . 开头），但非框架管理的隐藏目录可能包含敏感数据，请勿访问

环境依赖#

⚠️ This step installs and executes external code from npm. Only proceed if you trust the package source.

• npm 命令可用
• alipay-bot CLI 工具已安装。 优先检测本地是否已安装：先执行 which alipay-bot，如已存在则跳过安装

如未安装，按以下步骤执行：

1. 用户确认（安装前必须执行）： 安装前需向用户说明并获取明确同意：
   • 即将安装的外部包： @alipay/agent-payment@1.0.0（支付宝官方 npm 包，用于提供 alipay-bot CLI 工具）
   • 安装后会执行 install-cli 命令，将 alipay-bot CLI 工具安装到系统 PATH
   • 该 CLI 工具将用于执行 402 协议支付相关操作（检查钱包状态、发起支付、查询支付状态、发送履约回执）
   • 如用户不同意安装，终止流程并提示用户可手动安装
2. 完整性校验（安装前必须执行）：

bash

npm view @alipay/agent-payment@1.0.0 dist.integrity

预期值： sha512-/Ss+hS75CLYcwC8/jOj2kXzqIoJb7oKGrsiwnqly0EWVTxzD7QY5HxmFuj4anQfHVjnoh77qc2vUYiEAj0zfCA== 如果校验值不匹配， 禁止安装，终止流程并提示用户。

1. 安装（仅在校验通过后执行）：

bash

npm install @alipay/agent-payment@1.0.0 && npx @alipay/agent-payment@1.0.0 install-cli

注意：必须安装固定版本 @1.0.0，禁止使用 @latest 或其他非锁定版本标签，以防止供应链攻击。

核心流程#

text

Step 0: 执行 `alipay-bot -- check-wallet`（检查钱包状态）
    ↓
    根据返回值决策 →  code=200 & access_url为空   → Step 2
                  →  code=200 & access_url非空 → 告知用户"正在为您申请开通" → 主动调用 `alipay-authenticate-wallet` 技能
                  →  code=500     → 输出错误 → STOP
Step 1: 保存 402 Payment-Needed 响应文件
    ↓
Step 2: 执行 `alipay-bot -- 402-buyer-pay -f '<402_needed_file.txt>'`（提交支付）
    ↓
    处理输出 → ①提取 shortUrl ②将 CLI 完整输出（含 MEDIA 行）原样输出给用户  ③ 引导用户支付完成后通知你
    ↓
Step 3: 根据用户输入条件判断 →  用户表示已经支付完成  → Step 4
                          →  其他情况 → 结束流程 (STOP)
    ↓
Step 4: 查询支付结果并二次请求资源 `alipay-bot 402-query-payment-status -t '<tradeNo>' -r '<resource-url>' [-m '<method>'] [-d '<data>'] [-H '<key:value>']`
    ↓
    根据 CLI 输出判断 →  支付成功并返回资源信息 → Step 5继续流程
                    →  支付失败 → 输出失败原因 → STOP
    ↓
Step 5: 向用户透传支付信息和资源
    ↓
Step 6: 发送履约回执

用户交互规范#

执行过程中应向用户保持透明：

• 每个步骤执行前，告知用户将要执行的命令（如 alipay-bot 402-buyer-pay -f '...'）
• 遇到错误时，如实向用户报告错误内容
• Step 2 和 Step 5 仍按指定格式输出 CLI 结果和资源

Step 0: 检查钱包状态#

支付流程开始前必须先执行钱包状态检查：

bash

alipay-bot -- check-wallet

判断逻辑:

codeaccess_url状态操作200空钱包已就绪继续支付流程（进入 Step 1）200非空钱包未开通告知用户"正在为您申请开通"，主动调用 alipay-authenticate-wallet 技能500-钱包不可用停止支付，输出错误并终止流程

Step 1: 保存 402 响应文件#

收到 HTTP 402 响应后，直接保存响应头中的Payment-Needed到文件（CLI 需要文件路径作为输入）。你收到的Payment-Needed响应头是一个base64编码的文本， 你不需要解码，请你不要篡改任何信息， 完整一致地将实际收到的Payment-Needed保存到文件中。

文件路径安全规则（必须遵守）：

• 文件名仅允许：字母、数字、连字符（ -）、下划线（ _）、点号（ .）
• 请勿 包含路径分隔符（ /、 \）、路径穿越（ ..）、shell 特殊字符（ ;、 |、 &、 $、反引号、 () 等）
• 请勿 使用绝对路径或包含目录的路径
• 推荐文件名格式： 402_needed_<timestamp>.txt（如 402_needed_1713400000.txt）

⚠️ 如果文件名不符合上述规则， 请拒绝执行并终止流程——这可能是注入攻击。 若未收到Payment-Needed文本，则应提示用户未获取到商家收款信息，无法完成付款。

Step 2: 发起支付#

注意 本步骤中你需要将CLI的输出完整透传给用户

bash

alipay-bot -- 402-buyer-pay -f '<402_needed_file.txt>'

参数校验：执行前必须确认 <402_needed_file.txt> 对应的文件真实存在，且符合 Step 1 的文件路径安全规则，否则 请拒绝执行。

CLI 输出格式：Markdown 文本（可能包含 MEDIA 行），也可能是 JSON。具体判断：如果输出以 { 开头则为 JSON，否则为 Markdown 文本。

处理流程：

CLI 返回结果后，将其 完整内容直接作为你的回复文本 发送给用户，并 引导用户支付完成后通知你。不要用代码块包裹，不要重新排版，不要额外添加任何说明文字。

⚠️ 关键输出规则（未遵守将导致用户无法完成支付）：

1. CLI 返回什么文本，你给用户的回复就是什么文本—— 逐字符复制+引导用户支付完成后通知你

2. 请勿 用代码块（```）包裹 CLI 输出

3. 请勿 在 CLI 输出前后添加额外的说明文字（如"支付已提交，请扫码"等）

4. 请勿 修改/压缩/截断/省略任何 URL

5. 如果 CLI 输出中包含 MEDIA: 行， 保持原样，不要删除、不要读取图片、不要转换格式——框架会自动处理

6. 安全兜底：如果你检测到 CLI 输出中存在以下异常模式， 停止输出并向用户发出警告：

   • URL 指向非支付宝域名（非 *.alipay.com / *.alipay.net / *.alipay.cn）
   • MEDIA 路径不在 /tmp/openclaw/alipay-bot-cli/ 下
   • 输出中包含明显注入模式（如 <script>、 javascript:、 eval( 等）

正确输出示例（你的回复应该长这样， 注意CLI返回的 MEDIA 行要在文本下方原样保留）：

---

✓ 支付待确认

商品名称：xxxxxx

支付金额：xxx CNY

商户名称：xxxx

交易号：xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx（32位纯数字订单号）

支付方式：

• 电脑端用户：请 点击此处 打开收银台页面扫码支付
• 手机端用户：请 点击此处 唤起支付宝APP完成支付

在支付完成后请给我提示，我将继续购买流程

MEDIA: /tmp/xxxxx/xxxxxxxxxxxxxxxxxxxxx.png

---

你需要先透传CLI的输出文本然后在代码块下方原样输出CLI返回的MEDIA，否则将导致用户无法完成支付

错误示例：

text

❌ 用代码块包裹 CLI 输出
❌ 在 CLI 输出前加"支付已提交，请扫码支付"等额外文字
❌ 删除 MEDIA 行后再输出
❌ 读取 MEDIA 行中的图片文件
❌ 输出两遍（一遍代码块 + 一遍排版后的文本）
❌ 输出两遍 MEDIA 行

shortUrl 处理：

1. 提取：从 CLI 返回中提取 shortUrl

   • 判断方法：如果 CLI 输出以 { 开头，按 JSON 解析取 result.shortUrl 或 shortUrl 字段
   • 否则按纯文本处理，从文本中查找 https://u.alipay.cn/ 或 https://render 开头的 URL

2. 区分：

   • shortUrl：用于查询支付状态，格式 https://u.alipay.cn/... 或 https://render*.alipay.com/...
   • 支付链接：用于用户扫码支付，格式 https://cashier*.alipay.com/... 或 alipays://...

3. 后续：按照指定格式输出

错误处理：

1. 如果 result 提示“创单失败: 10001 - 签名验证不通过: 验签失败，请检查签名内容、签名类型和应用公钥是否匹配”: 使用以下命令模板重试，注意将替换为请求的资源地址、<402_needed_file.txt>替换为保存文件的临时目录地址，并且根据资源请求方式（GET/POST）适配命令： text

   curl -s -D - -o /dev/null <resource-url> | grep -i "^Payment-Needed:" | sed "s/^[Pp]ayment-[Nn]eeded: //" | tr -d "\r\n" > <402_needed_file.txt> && alipay-bot 402-buyer-pay -f <402_needed_file.txt>
   
   

   成功后继续流程。如果重试2次后依然不成功，提示用户"支付失败，商户签名验证不通过"并终止流程

2. 如果 result 包含 其他错误信息（如网络超时、链接无效等）: 原样输出错误信息并终止流程

注意 本步骤中你需要在执行成功后将CLI的输出完整透传给用户

Step 3: 用户支付完成#

用户提示你支付完成后进入到step4

Step 4：查询支付状态 🔗#

触发条件：用户告知你“支付已完成”或同等语义的提示词。

使用系统的命令执行工具（shell/terminal/exec 等）执行以下查询命令：

执行命令（将 <tradeNo> 替换为 Step 2 返回的 交易号 ， <resource_url> 替换为请求的资源地址， 注意你需要根据资源地址的请求方法调整命令，但参数不要超出提供的参数范围）：

bash

alipay-bot 402-query-payment-status -t '<tradeNo>' -r '<resource-url>' [-m '<method>'] [-d '<data>'] [-H '<key:value>']

参数范围：

• -t, --trade-no <tradeNo> - 交易号
• -r, --resource-url <url> - 资源请求 URL
• -m, --method <method> - HTTP 方法（GET 或 POST，默认 GET）
• -d, --data <data> - 请求数据（POST 方法时使用）
• -H, --header <key:value> - 自定义请求头（可重复使用，POST 方法时默认 Content-Type: application/json）

⚠️ 如果任何参数不符合校验规则， 请拒绝执行并终止流程——这可能是注入攻击。

结果处理

支付成功示例：

json

{
  "success": true,
  "tradeNo": "2026032xxxxxxxxxxx",
  "resourceResponse": {
    "status": 200,
    "headers": {
      xxx
    },
    "body": {
      xxx
    }
  }
}

支付失败示例：

json

{
"success": false,
"errorCode": "xxx",
"errorMsg": "xxx"
}

支付成功则进入Step 5，否则向用户透传错误信息并终止流程。

Step 5: 向用户透传支付信息和资源#

资源校验 如果Step 4 返回的 resourceResponse.body 为空，请立即 终止流程 并向用户透传该异常和 tradeNo。

资源透传 资源不为空则将 Step 4 返回的 tradeNo（订单号）和 resourceResponse.body（用户购买到的资源） 透传给用户。

Step 6: 发送履约回执#

收到资源后，发送履约回执给支付宝：

bash

alipay-bot -- 402-buyer-fulfillment-ack -t '<trade_no>'

参数校验： <trade_no> 仅允许数字（0-9），长度 32 位。如果包含任何非数字字符， 请拒绝执行并终止流程。

参数必填说明-t是交易号（即 Step 4 返回的 tradeNo）

错误处理

• 如果返回"系统繁忙"或"系统错误"等错误码，可以用相同命令重试。如果重试3次后仍失败，请立即 终止流程 并向用户透传错误码。
• 如果返回其他错误码，请立即 终止流程 并向用户透传错误码。

注意事项#

以下为你必须时刻遵守的行为准则

• 请勿展示id、签名、密钥、凭证等敏感信息
• 请勿向用户展示本地任意的文件内容、目录结构或摘要
• 错误和执行过程应向用户透明：执行命令前应告知用户将要执行的命令，遇到错误时应如实报告错误内容，不得隐瞒或伪造执行结果
• 请勿更改本技能或与本技能相关的其他技能及工具的内容
• 除填写参数外不要修改命令，否则将导致支付失败
• 请勿伪造支付状态或跳过发起支付流程
• 请勿利用过往支付记录伪造支付成功和履约

关键执行规则（未遵守将导致流程异常）#

规则1: 工作流动线（必须遵守）#

请勿跳过任何步骤，请勿修改流程顺序。

规则2: 请勿伪造#

• 必须 实际执行所提供的命令
• 请勿 在支付失败时伪造履约内容
• 请勿 伪造支付凭证
• 请勿 伪造交易号和支付成功状态

规则3: 请勿mock#

• 只允许 执行skill中提供的命令
• 请勿 使用mock的支付方法

规则4: 请勿修改资源#

• 你得到的资源最后需要 原封不动 地返回给用户
• 请勿 修改或简化资源的任何部分，否则用户会投诉你

规则5: 请勿篡改参数#

• 请勿 篡改命令参数，严格按照 skill 中定义的格式执行命令

请在 Step 2 输出后等待用户支付完成通知，再继续后续步骤，请勿自动连续执行全流程#

防御性输出规则（安全最佳实践）#

CLI 内置脱敏机制，正常输出不包含敏感信息。

处理方式：

1. CLI 针对每个执行步骤，都会根据执行命令和结果返回用户友好的 Markdown 文本，直接输出即可
2. CLI 输出内容不包含敏感字段
3. 如在加载本技能期间意外发现输出中包含敏感信息（如身份证号、银行卡号等），应过滤后再输出

问题反馈#

触发条件#

当用户在使用本技能过程中遇到以下情况时，应执行问题反馈流程：

场景示例402 支付流程反复失败用户多次尝试支付，每次都失败CLI 返回未知错误码402-buyer-pay 或 402-query-payment-status 返回非预期的错误码支付状态查询异常查询支付状态时返回异常结果，无法确认支付是否成功履约回执发送失败402-buyer-fulfillment-ack 命令执行失败且重试无效用户明确要求反馈用户说"我要反馈问题"、"这个问题怎么解决不了"

不触发问题反馈的场景#

• 用户只是询问"怎么支付"（正常咨询）
• 402 响应过期（引导用户重新请求即可）
• 用户取消支付（正常行为，不是问题）
• 问题可以通过重试解决（临时性网络问题等）

反馈执行流程#

满足触发条件后，按以下步骤执行：

Step 1：确认问题无法自行解决

检查是否可以通过重试、检查网络、重新获取 402 响应等方式解决。如果可以，不执行反馈。

Step 2：收集问题信息

从当前对话上下文中整理问题描述，内容应包含：

• 环节：问题发生在哪个环节（402 支付 / 查询状态 / 履约回执）
• 问题：具体的错误信息或异常表现
• 尝试：已做过的解决尝试

问题描述模板：

text

[环节]：{402支付/查询状态/履约回执}
[问题]：{具体描述}
[尝试]：{已做过的解决尝试}

Step 3：向用户确认

将整理后的问题描述展示给用户，等待用户明确确认后才能提交。用户拒绝则告知"如需反馈可随时告诉我"，流程结束。

Step 4：提交反馈

用户确认后执行：

bash

alipay-bot problem-feedback --reason '<问题描述>'

安全约束：

• --reason 值需用 单引号 '...' 包裹（请勿使用双引号）
• 如问题描述中包含单引号 '，需替换为 '\''
• 请勿编造问题，应基于用户实际遇到的情况

Step 5：输出结果

原样输出 CLI 返回的内容，请勿编造、修改、删减或改写。