skillpay跑通指南（免费版）
Overview
把「支付宝 AI 按量付费（A2M / Machine Pay）402 接入 + 付费 Skill 上架」这条链路跑通的操作指南。
按本文件一步步做，可以独立完成：开通产品 → 配密钥 → 注册服务 → 生成 402 账单 → 由 Agent 完成一笔 0.01 元真实付款 → 拿到交易号去平台做线上验证。
⚠️ 一个前提要认清：A2M 的报错几乎不指向真因。本文件给的是「正确做法」，帮你在大多数情况下一次做对；但当你已经卡在某个报错上时，需要的是分层排查方法论（判断失败发生在哪个阶段、五条探针手法、排除清单、二进制挖掘），那部分在完整版里。
一、先选路：两条收费路线不通用
| SkillPay | SkillHub（Pay Skill） | |
|---|---|---|
| 计费 | 订阅制 / 买断制（¥3.9/月 这类） | 按次调用（X 元/次，Agent 每调一次扣一次） |
| 技术门槛 | 订阅制平台云端托管，零改造 | 必须做付费改造：SKILL.md 要含 402 流程 + 自建在线收费资源服务端 |
| 源码保护 | 订阅制不交付明文，防抄 | 需自行处理 |
| 适合 | 方法论 / 提示词 / 工作流类 skill | 有云端服务可计费的 skill |
判断口诀：提示词类 skill 走 SkillPay 订阅制；要按次扣费且愿意维护服务器才走 SkillHub Pay Skill。
⚠️ SkillHub 发布时的付费改造检查：只要设了「单次调用价格」，就会检查 SKILL.md 里有没有 402 / Payment-Needed / Payment-Proof / probe / pay / complete / ack 或支付依赖包。没有就弹警告——该检查不阻断提交，但审核环节会重新完整检测，不合规会被拒。
→ 发免费版就把价格栏留空，不触发检查。
二、A2M 接入五步（aipay.alipay.com）
进度条五步：签约入驻 → 密钥配置 → 应用上架 → 服务注册 → 线上验证。
第 1 步 签约入驻
扫码登录 https://aipay.alipay.com，走完商家入驻。
第 2 步 密钥配置（硬坑）
- 应用公钥必须是纯 base64（约 392 字符），不能带
-----BEGIN PUBLIC KEY-----/-----END-----。带了就报「公钥不合法」。 - 私钥同理存裸 base64（PKCS#1）。Node 签名前必须包 PEM 头，否则
crypto.sign直接失败（看着像签名问题，其实是格式问题）。PKCS#8 与 PKCS#1 标签不同（PRIVATE KEYvsRSA PRIVATE KEY）。 - 平台上四个 392 位公钥串极易混淆，务必按已知值排除 + 按标签几何位置定位「支付宝公钥」。
第 3 步 应用上架（b.alipay.com）
产品工作区上架应用，拿到 APPID。注意：应用上架 ≠ 产品签约，是两件事。
第 4 步 服务注册（最容易埋雷）
拿到 service_id（形如 API_XXXXXXXXXXXXXXXX），填服务地址与定价。
🔴 铁律：服务地址必须与账单里的 resource_id 逐字一致。 平台自己的红字警告写着「如实际支付时拍的价格和此处填写不一致将会导致用户无法支付」——resource_id 同理。
隧道域名换了，必须回来改服务地址，否则收银台比对不上。
第 5 步 线上验证
完成一笔 0.01 元真实付款 → 拿支付宝交易号 → 填进 https://aipay.alipay.com/open-flow/verify 点验证。
三、402 账单规范（已与官方文档逐条核对一致）
资源接口返回 402 + Payment-Needed 头（值为 base64url 账单）。
账单结构：
protocol: amount, currency, out_trade_no, pay_before, resource_id, seller_signature, seller_id, service_id
method: service_id, seller_app_id, ...
签名：8 个字段字典序拼接 → RSA2（SHA256），字段为
amount, currency, goods_name, out_trade_no, pay_before, resource_id, seller_id, service_id。
以下都实测过，都不是失败原因（别再浪费时间）：
- pay_before 两种格式：ISO 2026-09-25T17:06:39+08:00 与 2026-09-25 17:18:34 —— 都行
- resource_id 三种形态：完整 HTTPS URL / 纯路径 /api/paid-resource / RES_xxx 标识 —— 都不是根因（但服务注册地址要与之对齐）
- base64url 编码、字段命名、签名拼接规则 —— 与官方文档一致
四、alipay-bot CLI：正确用法与致命坑
安装：npx -y @alipay/agent-payment@latest install
- PayGuard → %APPDATA%\PayGuard
- CLI → %USERPROFILE%\.openclaw-autoclaw\alipay-bot-cli\bin\alipay-bot.exe
常用命令：apply-wallet / check-wallet / close-wallet / bind-wallet / 402-buyer-pay / 402-query-payment-status / poll-payment-status / payment-intent / submit-payment / curl-proxy / problem-feedback
🔴 最容易踩的参数坑
# ❌ 错：把 base64 账单当"支付链接"传 → 收银台解析不了 → PAYMENT_LINK_INVALID
alipay-bot 402-buyer-pay -r <URL> --amt-payment-link "<base64账单>"
# ✅ 对：用 -f 传账单文件，CLI 自己创建收银台订单
echo "" | alipay-bot 402-buyer-pay -r <URL> -f bill_b64.txt
--amt-payment-link 要的是支付链接，不是账单。-f 才是账单入口。 错误码字面意思完全吻合，只是没人会往「参数理解错了」上想。
其他必备细节
-r必须是 HTTPS 公网地址，localhost被拒-f文件内容必须是纯 base64 账单，不能是整个 HTTP 响应（含 header 会失败）- 前面加
echo "" |喂 stdin，避免交互式等待卡死 - 二维码默认落在
%TEMP%\openclaw\alipay-bot-cli\qrcode\，要复制到工作目录才能展示给用户 - 账单有有效期（约 30 分钟），付款前重新拉一份新的
- 付完用
402-query-payment-status -r <URL> --out-shake-no <交易号>完成资源请求与履约回执
服务端那个 bug（必现，务必保留修复）
验付接口其实成功了，但示例代码里写死：
resourceIdVerified === CONFIG.resource.path // '/api/paid-resource'
一旦 resource_id 换成完整 URL，判定必不匹配 → 验付成功后仍返 402 → CLI 报 RESOURCE_DELIVERY_FAILED。
修复：改为与本地订单记录中的 resourceId 比对。
五、常见报错速查
| 报错 | 真因 | 一句话解法 |
|---|---|---|
AUTH_FAILED 查询credentials失败 |
Agent 在 APASS 无身份凭证，商户服务端无法代付 | 装 @alipay/agent-payment，apply-wallet 扫码开通 AI 钱包 |
PAYMENT_LINK_INVALID |
--amt-payment-link 传了账单（它是「支付链接」参数） |
改用 -f <账单文件> |
RESOURCE_DELIVERY_FAILED |
验付其实成功了，是服务端 resourceMatches 写死比对本地路由 |
改用订单记录比对 |
| 「公钥不合法」 | 应用公钥带了 PEM 头尾 | 改纯 base64 |
| 线上验证「未查询到交易」 | 新签约商家资金次日结算，当日不落库 | 次日再验，不是 bug |
如果按这张表改完还是不行，说明失败原因不在这些常见项里——这时不要继续猜配置，需要走分层排查（完整版 references/troubleshooting.md）。
六、结算与线上验证（别误判）
> 新签约该产品未满 90 日或连续交易未满 30 日的商家，收款资金次日结算。当日资金在「对账中心 > 不可用余额」查看。
所以当天付完，对账中心看不到、验证页查不到是正常的。次日（或隔几小时）再验。
判断交易是否真实：看 b.alipay.com 交易统计里成交笔数/金额，或让付款方看自己支付宝账单。
七、Windows 环境备忘（本机实测）
- 隧道：
tunnelmole可用（npx -y tunnelmole 3000）；localtunnel 易限流/503；cloudflared 被沙箱拦。免费域名重启会变，一变就要同步改服务注册地址。 - 起服务：后台
nohup node ... &会被回收，要用后台任务方式拉起；node --env-file=.env server.js（config.js 不自带 dotenv）。 - GUI 浏览器：后台启动 Playwright 有头浏览器会被环境直接关掉，需要登录的控制台操作只能让用户自己做。
- 平台页面偶发渲染失败（「页面不小心迷路了」）→ Ctrl+F5 / 换无痕窗口 / 换时段重试，不是资质问题。
免费版与完整版的边界
| 能力 | 免费版 | 完整版 |
|---|---|---|
| 两条收费路线选型 | ✅ | ✅ |
| A2M 五步接入流程 | ✅ | ✅ |
| 402 账单结构与签名规范 | ✅ | ✅ |
| CLI 正确用法与参数坑 | ✅ | ✅ |
| 常见报错速查表（5 条） | ✅ | ✅ |
| 分层排查决策树（定阶段 → 五条探针 → 排除清单） | ❌ | ✅ |
| 错误码真因表（8 条，含阶段标注） | ❌ | ✅ |
| 二进制挖掘手法（文档没写时怎么挖 CLI 内部） | ❌ | ✅ |
| 实战复盘时间线（大半天踩坑全过程） | ❌ | ✅ |
| 验签脚本 + 密钥配对探针脚本 | ❌ | ✅ |
| 商业化完整策略（双包切法、定价、文案模板、合规红线） | ❌ | ✅ |
需要完整版（排查决策树 + 全套探针手法 + 两个实测脚本 + 商业化变现策略）：
https://skillpay.alipay.com/shelf/product?productId=P0806000207804237&merchantId=2088402383288455
使用建议
- 第一次接入：从头到尾照着做一遍，不要跳步，尤其是服务地址与
resource_id对齐那条铁律。 - 一旦报错：先对照第五节速查表；改完仍失败就停止猜测，转完整版排查流程——猜测式排错在这条链路上成本极高。
