@itpay/cli 2.0.15 → 2.0.16

package/docs/cli-reference/agent-types.md

@@ -15,6 +15,8 @@
 | `claude-code-desktop` | `claude-code` | 返回桌面对话可展示的 Markdown 图片和付款链接，要求先展示再等待。 |
 | `claude-code-cli` | `terminal` | 在用户可见终端输出二维码和链接，不声称已在桌面对话展示。 |
 | `workbuddy` | `plain-chat` | 只返回 HTTPS 二维码和付款链接；要求 Agent 用 `present_files` 在右侧预览打开二维码，不返回或检查本地图片路径。 |
+| `kimi-code` | `terminal` | 使用标准 CLI 引导，在用户可见终端渲染二维码和付款链接。 |
+| `openclaw` | 无；必须显式传入 | `--host telegram` 使用 OpenClaw 原生 `message` action；其他入口返回标准 HTTPS 二维码和付款链接。 |
 
 ## 通用规则
 
@@ -24,8 +26,11 @@
 - 显式 `--host` 覆盖默认 Host，但不改变已登记的 Agent Type。
 - `--target` 只路由人类展示，不是身份，也不是 capability 业务输入。
 - Host 只影响 `instruction` 和 `handoff`，不得改变金额、订单、权限、quota 或交付状态。
-- 五种 Agent Type 使用同一命令输入和 JSON 外壳；不得为单个 Agent Type 新增、删除或改名协议字段。
-- 非展示命令在五种 Agent Type 下返回相同业务结果，只允许 `instruction` 措辞不同。只有 Host 客观无法展示某种媒介时，`handoff` 才按既有可选字段做最小裁剪。
+- 七种 Agent Type 使用同一命令输入和 JSON 外壳；OpenClaw 只在 `handoff` 的既有扩展位置增加平台 action，不改变交易字段。
+- 非展示命令在七种 Agent Type 下返回相同业务结果，只允许 `instruction` 措辞不同。只有 Host 客观无法展示某种媒介时，`handoff` 才按既有可选字段做最小裁剪。
+- `openclaw` 没有默认 Host。展示命令必须显式传 `--host`；缺少时在任何 Checkout 创建或状态迁移前返回 `host_required`。
+- OpenClaw 的 IM Host 必须提供 `--target`。缺失时在任何 Checkout 创建前返回 `target_required`。
+- `kimi-code` 是 CLI 型 Agent，复用 `terminal` Host 和现有 CLI 展示，不增加 Kimi 专属交易协议。
 - session 失效时 CLI 只续期并重试原请求一次；再次失败立即返回。revoked v2 Device 不自动换身份。
 
 ## Checkout Handoff 最小合同
@@ -62,5 +67,10 @@
 | `codex-cli / terminal` | `url`；非 JSON 输出另外渲染终端二维码 |
 | `claude-code-cli / terminal` | `url`；非 JSON 输出另外渲染终端二维码 |
 | `workbuddy / plain-chat` | `url, qr_image_url` |
+| `kimi-code / terminal` | `url`；非 JSON 输出另外渲染终端二维码 |
+| `openclaw / telegram` | `url, qr_image_url, agent_action` |
+| `openclaw / other` | `url, qr_image_url` |
 
 WorkBuddy instruction 只在 `handoff.qr_image_url` 存在时要求读取其完整字符串并作为 `files` 数组唯一元素调用 `present_files`。如果该可选字段不存在，必须直接发送 `handoff.url`，明确不要调用 `present_files`。两种情况都要停止等待；不能检查本地文件、下载或重建二维码、调用 `pay` 或创建替代付款资源。显式 `--host` 仍覆盖默认展示方式，因此只有 `workbuddy + plain-chat` 使用该规则。
+
+OpenClaw Telegram 的 `handoff.agent_action` 使用原生 `message` tool，包含当前 `target`、二维码 media、付款链接和 typed Presentation actions。URL 按钮使用 `action.type=url`；只读查询按钮使用 `action.type=callback`，callback 只携带 Checkout ID，不携带 display token，也不构成付款证明。

package/docs/cli-reference/commands/buy.md

@@ -62,8 +62,8 @@ itpay buy \
 | `--contact-email` | 条件必填 | 普通 Cart 或兼容旧 Quote 缺少所需邮箱时使用，值必须来自用户；新版 Service Quote 会自动携带已确认邮箱。 |
 | `--contact-phone` | 条件必填 | `--require-contact` 包含 `phone` 时必填，值必须来自用户。 |
 | `--require-contact` | 否 | 只接受 `email`、`phone`；缺失时先询问用户，禁止 Agent 编造。 |
-| `--host` | 否 | 默认由 `--agent-type` 推导；只改变 handoff 展示，不改变交易事实。 |
-| `--target` | 条件必填 | 只有要求目标会话的 IM Host 才需要；当前首批五种 Agent Type 无需提供。 |
+| `--host` | 条件必填 | 通常由 `--agent-type` 推导；`openclaw` 必须显式传当前入口。只改变 handoff 展示，不改变交易事实。 |
+| `--target` | 条件必填 | 要求目标会话的 IM Host 必须提供；OpenClaw 从当前可信会话上下文传入。 |
 | `--qr-format` | 否 | 非 JSON 的终端渲染选项。 |
 | `--qr-file` | 否 | 非 JSON handoff 的明确二维码文件路径。 |
 | `--pay` | 否 | 创建 Payment Intent 的集成/运维入口；普通 Agent 流程只展示 Checkout。 |
@@ -91,7 +91,8 @@ itpay buy \
     "url": "<tokenized_checkout_url>",
     "qr_local_path": "<desktop_optional_host_ready_file>",
     "markdown": "<desktop_only_optional_markdown>",
-    "qr_image_url": "<workbuddy_only_absolute_https_png>"
+    "qr_image_url": "<chat_host_optional_absolute_https_png>",
+    "agent_action": "<openclaw_telegram_only_native_message_action>"
   },
   "instruction": "<current_host_instruction>",
   "next": {
@@ -102,7 +103,7 @@ itpay buy \
 }
 ```
 
-`handoff` 只保留当前 Host 可以使用的字段。不得返回二维码 base64、镜像路径数组、renderer 状态、原始后端 DTO 或重复的 `agent_action`。
+`handoff` 只保留当前 Host 可以使用的字段。不得返回二维码 base64、镜像路径数组、renderer 状态或原始后端 DTO。`agent_action` 只允许出现在 `openclaw + telegram`。
 
 **Instruction：** 必须使用下方 Agent Type 表定义的展示动作；展示完成或失败后停止。只有用户明确表示已付款或要求查询时才执行 `next.command`，并以后端状态为准。
 
@@ -165,5 +166,9 @@ itpay buy \
 | `claude-code-desktop` | `claude-code` | `url`、可用时 `qr_local_path` 和 `markdown` | 把 Markdown handoff 发到当前桌面对话，不能只输出本地路径。 |
 | `claude-code-cli` | `terminal` | `url` | 在用户可见终端展示；不能声称桌面对话已收到图片。 |
 | `workbuddy` | `plain-chat` | `url, qr_image_url?` | 有 `qr_image_url` 时调用 `present_files`；没有时只发送金额和 `url` 且不调用工具。两者都停止，不读取本地文件。 |
+| `kimi-code` | `terminal` | `url` | 使用标准 CLI 非 JSON 终端二维码和链接。 |
+| `openclaw` | 必须显式 | Telegram 返回 `url,qr_image_url,agent_action`；其他入口返回 `url,qr_image_url` | Telegram 执行原生 `message` action；其他入口直接展示图片和链接。 |
 
 显式 `--host` 可以覆盖展示方式，但不会改变 Agent Type、设备身份、金额、权限或交易状态。
+
+OpenClaw 缺少 `--host`，或 IM Host 缺少 `--target` 时，必须在创建 Cart/Checkout 前分别返回 `host_required` 或 `target_required`。

package/docs/cli-reference/commands/cart/add.md

@@ -85,4 +85,4 @@ Quote 模式返回：
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种类型都写入真实 Agent Type。默认 Host 分别是 `codex`、`terminal`、`claude-code`、`terminal`、`plain-chat`。业务输出合同相同；此命令本身不显示二维码。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种类型都写入真实 Agent Type。默认 Host 分别是 `codex`、`terminal`、`claude-code`、`terminal`、`plain-chat`。业务输出合同相同；此命令本身不显示二维码。

package/docs/cli-reference/commands/cart/clear.md

@@ -52,4 +52,4 @@ itpay cart clear [--local] [--json]
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 行为相同。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 行为相同。

package/docs/cli-reference/commands/cart/index.md

@@ -29,4 +29,4 @@ itpay cart --help
 
 ## Agent Type / Host
 
-Cart 事实在 `codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 下相同；`add` 创建 client context 时记录真实 Agent Type 和 Host。
+Cart 事实在 `codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 下相同；`add` 创建 client context 时记录真实 Agent Type 和 Host。

package/docs/cli-reference/commands/cart/next.md

@@ -70,4 +70,4 @@ itpay buy --cart <cart_id> --json
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 的业务字段、instruction 和 next 相同。本命令不产生二维码或 Host handoff。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 的业务字段、instruction 和 next 相同。本命令不产生二维码或 Host handoff。

package/docs/cli-reference/commands/cart/remove.md

@@ -52,4 +52,4 @@ quote/checkout 已锁定时返回 `cart_item_locked`，要求继续已有 Checko
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 行为相同。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 行为相同。

package/docs/cli-reference/commands/cart/show.md

@@ -64,4 +64,4 @@ canonical 输出不得包含 Catalog variant/offer、line input、Service quote
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 行为相同。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 行为相同。

package/docs/cli-reference/commands/catalog/index.md

@@ -25,4 +25,4 @@ itpay catalog --help
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种支持类型的目录事实完全相同。instruction 可按 Agent Type 调整措辞，但不得改变服务排序、价格或可用能力。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种支持类型的目录事实完全相同。instruction 可按 Agent Type 调整措辞，但不得改变服务排序、价格或可用能力。

package/docs/cli-reference/commands/checkout.md

@@ -18,7 +18,7 @@ itpay checkout [--id <checkout_id>] [--token <display_token>]
 
 省略 `--id/--token` 时只能使用本机保存的一组完整句柄；不得把其他 Checkout 的 token 拼接使用。
 
-`--host` 默认由 `--agent-type` 决定。`--target` 为现有 IM Host 兼容参数；当前五种 Agent Type 不需要它。`--json` 输出机器可读合同，不内嵌二维码字符画或图片二进制。
+`--host` 默认由 `--agent-type` 决定；`openclaw` 必须显式传当前入口。IM Host 必须提供 `--target`。`--json` 输出机器可读合同，不内嵌二维码字符画或图片二进制。
 
 ## 等待付款输出
 
@@ -26,7 +26,7 @@ itpay checkout [--id <checkout_id>] [--token <display_token>]
 {
   "status": "human_checkout_required",
   "result": { "checkout_id": "<checkout_id>", "payment": "pending", "amount": "<amount> <currency>" },
-  "handoff": { "url": "<checkout_url>", "qr_local_path": "<desktop_optional_path>", "qr_image_url": "<workbuddy_optional_absolute_https_png>", "markdown": "<desktop_optional_markdown>" },
+  "handoff": { "url": "<checkout_url>", "qr_local_path": "<desktop_optional_path>", "qr_image_url": "<chat_optional_absolute_https_png>", "markdown": "<desktop_optional_markdown>", "agent_action": "<openclaw_telegram_optional_native_message_action>" },
   "instruction": "<exact_agent_type_instruction>",
   "next": { "command": "itpay checkout --id <checkout_id> --token <display_token> --json", "reason": "稍后只查询同一 Checkout" },
   "recovery": []
@@ -72,5 +72,7 @@ token 缺失或不匹配时使用本机句柄恢复。只有请求的 Checkout
 | `claude-code-desktop` | `url, qr_local_path, markdown`；原样发送 Markdown。 |
 | `claude-code-cli` | `url`；普通文本模式渲染终端二维码。 |
 | `workbuddy` | `url, qr_image_url?`；有二维码 URL 时按 `services checkout` 相同规则调用 `present_files`，没有时只发送 Checkout URL，不生成本地文件。 |
+| `kimi-code` | `url`；普通文本模式渲染标准终端二维码。 |
+| `openclaw` | Telegram 为 `url,qr_image_url,agent_action`；其他显式 Host 为 `url,qr_image_url`。 |
 
-完成、退款或失效状态下五种 Agent Type 都只返回同一状态和下一步，不渲染二维码。
+完成、退款或失效状态下所有 Agent Type 都只返回同一状态和下一步，不渲染二维码。OpenClaw 的 `--target` 必须传入展示层，不能被 CLI 参数解析后丢弃。

package/docs/cli-reference/commands/docs/index.md

@@ -27,4 +27,4 @@ itpay docs --help
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 使用同一文档源；topic 内容可以包含各类型专属 section。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 使用同一文档源；topic 内容可以包含各类型专属 section。

package/docs/cli-reference/commands/docs/list.md

@@ -50,4 +50,4 @@ itpay docs show <topic> --json
 
 ## Agent Type / Host
 
-五种正式 Agent Type 返回相同结果。本命令没有 Host 渲染、设备登记或本地业务状态写入。
+七种正式 Agent Type 返回相同结果。本命令没有 Host 渲染、设备登记或本地业务状态写入。

package/docs/cli-reference/commands/docs/search.md

@@ -68,4 +68,4 @@ itpay docs search <query> [--json]
 
 ## Agent Type / Host
 
-五种正式 Agent Type 行为相同。本命令不产生 Host handoff。
+七种正式 Agent Type 行为相同。本命令不产生 Host handoff。

package/docs/cli-reference/commands/docs/show.md

@@ -67,4 +67,4 @@ topic 不存在返回 `doc_not_found`：
 
 ## Agent Type / Host
 
-五种正式 Agent Type 使用同一 topic。topic 若包含多种 Host 指导，Agent 只采用与自身 Agent Type 和当前 Host 匹配的部分。
+七种正式 Agent Type 使用同一 topic。topic 若包含多种 Host 指导，Agent 只采用与自身 Agent Type 和当前 Host 匹配的部分。

package/docs/cli-reference/commands/install.md

@@ -4,9 +4,9 @@
 
 ## 范围与意义
 
-读取当前 CLI 内置的 Agent Type 安装合同。它只说明 npm 安装、默认 API、默认 Host 和下一条验证命令；不修改宿主配置、不登记设备，也不调用 Backend。
+读取当前 CLI 内置的 Agent Type 运行合同。它只说明默认 API、默认 Host 和下一条验证命令；不安装 CLI、不修改宿主配置、不登记设备，也不调用 Backend。
 
-**上游：** 安装或更新 `@itpay/cli`。
+**上游：** 当前 npm CLI 或平台 bundle 已经可执行。
 
 **下游：** 使用真实 Agent Type 执行 `readyz`，随后读取完整 Skill 和 Catalog。
 
@@ -18,10 +18,10 @@ itpay install [target] [--json]
 
 | 参数 | 必填 | 说明 |
 | --- | --- | --- |
-| `target` | 否 | 五种正式 Agent Type 之一；省略或传 `list` 时列出全部。Host 名称不是合法 target。 |
+| `target` | 否 | 七种正式 Agent Type 之一；省略或传 `list` 时列出全部。Host 名称不是合法 target。 |
 | `--json` | 否 | 返回标准命令 envelope；推荐 Agent 使用。 |
 
-正式 target：`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`。
+正式 target：`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw`。
 
 ## 指定 Agent Type 输出
 
@@ -31,8 +31,7 @@ itpay install [target] [--json]
   "result": {
     "agent_type": "codex-desktop",
     "default_host": "codex",
-    "default_api": "https://app.itpay.ai",
-    "install_command": "npm install -g @itpay/cli"
+    "default_api": "https://app.itpay.ai"
   },
   "instruction": "在 Codex Desktop 中始终传这个 Agent Type；付款时把返回的二维码和链接实际展示到当前对话。",
   "next": {
@@ -48,11 +47,37 @@ itpay install [target] [--json]
 }
 ```
 
-`result` 是客观安装事实；`instruction` 只解释当前 Agent Type 的展示责任；`next` 只有一条可执行验证命令。
+`result` 是客观运行时事实；`instruction` 只解释当前 Agent Type 的展示责任；`next` 只有一条可执行验证命令。任何 target 都不得返回 npm 安装命令。
+
+OpenClaw 额外明确没有默认入口：
+
+```json
+{
+  "status": "instructions_ready",
+  "result": {
+    "agent_type": "openclaw",
+    "default_host": null,
+    "host_required": true,
+    "native_hosts": ["telegram"],
+    "default_api": "https://app.itpay.ai"
+  },
+  "instruction": "保持 openclaw Agent Type；每个展示命令都从当前可信会话上下文显式传 --host，IM 入口同时传 --target。Telegram 使用返回的原生 message action，其他入口展示标准二维码和付款链接。",
+  "next": {
+    "command": "itpay --agent-type openclaw readyz --json",
+    "reason": "验证当前官方 ItPay API 的可用性"
+  },
+  "recovery": [
+    {
+      "command": "itpay docs show install-and-setup",
+      "reason": "查看官方 Backend 和首次使用说明"
+    }
+  ]
+}
+```
 
 ## 列表输出
 
-省略 target 或传 `list` 时返回五组 `agent_type/default_host`，不重复每种类型的完整 instruction：
+省略 target 或传 `list` 时返回七组运行时定义，不重复每种类型的完整 instruction：
 
 ```json
 {
@@ -63,7 +88,14 @@ itpay install [target] [--json]
       { "agent_type": "codex-cli", "default_host": "terminal" },
       { "agent_type": "claude-code-desktop", "default_host": "claude-code" },
       { "agent_type": "claude-code-cli", "default_host": "terminal" },
-      { "agent_type": "workbuddy", "default_host": "plain-chat" }
+      { "agent_type": "workbuddy", "default_host": "plain-chat" },
+      { "agent_type": "kimi-code", "default_host": "terminal" },
+      {
+        "agent_type": "openclaw",
+        "default_host": null,
+        "host_required": true,
+        "native_hosts": ["telegram"]
+      }
     ]
   },
   "instruction": "选择当前真实运行环境；同一 Agent 不要临时更换 Agent Type。",
@@ -86,6 +118,8 @@ itpay install [target] [--json]
 | `claude-code-desktop` | `claude-code` | 桌面对话必须实际展示二维码和付款链接。 |
 | `claude-code-cli` | `terminal` | 只在用户可见终端展示付款交接。 |
 | `workbuddy` | `plain-chat` | 会持久化 `~/.itpay-v3` 的 Bash 调用先设 Shell 工具参数 `dangerouslyDisableSandbox=true`；拒绝权限时停止，不切换 Node、不删除 identity、不处理 lock。Checkout 返回 `qr_image_url` 时按 instruction 调用 `present_files`。 |
+| `kimi-code` | `terminal` | 使用标准 CLI 流程和终端展示，不增加 Kimi 专属命令。 |
+| `openclaw` | 无 | 必须显式提供当前入口；Telegram 使用原生 action，其他入口展示标准二维码和链接。 |
 
 显式 `--host` 可以在后续 commerce 命令覆盖默认 Host，但不会改变 Agent Type 或设备归属。
 
@@ -102,7 +136,7 @@ itpay install [target] [--json]
     "code": "unsupported_agent_type",
     "message": "unsupported install target: codex"
   },
-  "instruction": "target 只接受：codex-desktop, codex-cli, claude-code-desktop, claude-code-cli, workbuddy。",
+  "instruction": "target 只接受：codex-desktop, codex-cli, claude-code-desktop, claude-code-cli, workbuddy, kimi-code, openclaw。",
   "next": null,
   "recovery": [
     {

package/docs/cli-reference/commands/next.md

@@ -86,4 +86,4 @@ Checkout 句柄返回：
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 的状态、instruction 和下一步完全相同。本命令不产生二维码或 Host handoff。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 的状态、instruction 和下一步完全相同。本命令不产生二维码或 Host handoff。

package/docs/cli-reference/commands/readyz.md

@@ -62,7 +62,7 @@ itpay readyz [--json]
 }
 ```
 
-CLI 已取得 Backend 的兼容性合同、但当前版本或 contract hash 不匹配时，返回一个可执行且版本固定的恢复动作：
+CLI 已取得 Backend 的兼容性合同、但当前版本或 contract hash 不匹配时，返回一个可执行且版本固定的分发专属恢复动作。npm CLI 示例：
 
 ```json
 {
@@ -86,7 +86,31 @@ CLI 已取得 Backend 的兼容性合同、但当前版本或 contract hash 不
 }
 ```
 
-只允许使用 Backend 返回的 `minimum_cli_version` 生成精确 npm 版本。兼容性合同不可用、缺少合法版本或仅有无法验证的错误文本时，仍须停止且不得猜测安装版本。
+OpenClaw bundle 的同一错误改为：
+
+```json
+{
+  "status": "error",
+  "error": {
+    "code": "backend_contract_incompatible",
+    "message": "<same compatibility fact>"
+  },
+  "result": {
+    "current_cli_version": "2.0.15",
+    "required_cli_version": "2.0.16"
+  },
+  "instruction": "当前 OpenClaw Skill bundle 与 Backend 合约不兼容。停止所有 ItPay 业务命令；只执行 recovery.command，更新 Skill 后启动新会话并确认 itpay --version 与 result.required_cli_version 完全一致，再重新运行 readyz。不要运行 npm、切换 Agent Type 或删除 Device 身份。",
+  "next": null,
+  "recovery": [
+    {
+      "command": "openclaw skills update itpay",
+      "reason": "更新包含 Backend 指定 CLI 版本的 ItPay Skill bundle"
+    }
+  ]
+}
+```
+
+Kimi bundle 使用其 plugin 更新入口，不返回 npm 命令。只允许使用 Backend 返回的 `minimum_cli_version` 生成精确版本要求；兼容性合同不可用、缺少合法版本或仅有无法验证的错误文本时，仍须停止且不得猜测安装版本。
 
 ## Agent Type / Host
 

package/docs/cli-reference/commands/refund/cancel.md

@@ -61,4 +61,4 @@ itpay refund cancel <refund_request_id> [--reason <reason>] [--json]
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 的业务字段、instruction 和 recovery 相同；该命令没有二维码或宿主渲染差异。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 的业务字段、instruction 和 recovery 相同；该命令没有二维码或宿主渲染差异。

package/docs/cli-reference/commands/refund/create.md

@@ -84,4 +84,4 @@ CLI 使用 Device Authority 或已有 Buyer bearer，并用订单+原因生成
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 使用相同 Device Authority、退款政策和输出。未绑定订单时不得改用新 Device ID、Buyer ID 或开发者权限绕过 Owner 鉴权。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 使用相同 Device Authority、退款政策和输出。未绑定订单时不得改用新 Device ID、Buyer ID 或开发者权限绕过 Owner 鉴权。

package/docs/cli-reference/commands/refund/index.md

@@ -32,4 +32,4 @@ itpay refund --help
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种类型使用同一签名 Device Authority 和退款状态机；Host 不影响退款资格。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种类型使用同一签名 Device Authority 和退款状态机；Host 不影响退款资格。

package/docs/cli-reference/commands/refund/list.md

@@ -67,4 +67,4 @@ itpay refund list --order <order_id> [--json]
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 的业务字段、instruction 和 next 完全相同；本命令没有 Host 渲染差异。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 的业务字段、instruction 和 next 完全相同；本命令没有 Host 渲染差异。

package/docs/cli-reference/commands/services/action.md

@@ -47,4 +47,4 @@ rank 不存在、属于旧结果集或其他 Execution、action 不允许、stat
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 行为相同。需要人确认时 instruction 必须明确“先询问用户”，不能因 Desktop Host 自动代替用户选择。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 行为相同。需要人确认时 instruction 必须明确“先询问用户”，不能因 Desktop Host 自动代替用户选择。

package/docs/cli-reference/commands/services/checkout.md

@@ -34,7 +34,7 @@ itpay services checkout <service_execution_id> --resume
     "locked_input": { "<required_key>": "<value>" },
     "amount": "<amount> <currency>"
   },
-  "handoff": { "url": "<checkout_url>", "qr_local_path": "<desktop_optional_path>", "qr_image_url": "<workbuddy_optional_absolute_https_png>", "markdown": "<desktop_optional_markdown>" },
+  "handoff": { "url": "<checkout_url>", "qr_local_path": "<desktop_optional_path>", "qr_image_url": "<chat_optional_absolute_https_png>", "markdown": "<desktop_optional_markdown>", "agent_action": "<openclaw_telegram_optional_native_message_action>" },
   "instruction": "<exact_agent_type_instruction>",
   "next": { "command": "itpay checkout --id <checkout_id> --token <display_token> --json", "reason": "仅在用户完成付款操作或要求查询后，读取同一 Checkout 的权威状态" },
   "recovery": []
@@ -82,6 +82,8 @@ itpay services checkout <service_execution_id> --resume
 | `claude-code-desktop` | `handoff={url,qr_local_path,markdown}`；把 `handoff.markdown` 原样发送到当前桌面对话。 |
 | `claude-code-cli` | `handoff={url}`；普通文本模式在用户可见终端渲染二维码。 |
 | `workbuddy` | `handoff={url,qr_image_url?}`；有 `qr_image_url` 时读取完整值并作为 `files` 数组唯一元素调用 `present_files`；没有时直接发送金额与 `url`，不得调用 `present_files`。两者随后都停止，不得检查或生成本地文件。 |
+| `kimi-code` | `handoff={url}`；复用标准 CLI 终端展示。 |
+| `openclaw` | 必须显式传 Host；Telegram 还必须传 Target，并返回原生 `message` action；其他入口返回标准 `url,qr_image_url`。 |
 
 WorkBuddy 的准确 instruction 语义必须完整包含：
 
@@ -90,3 +92,5 @@ Backend 尚未确认付款。读取 handoff.qr_image_url 的完整字符串，
 ```
 
 若 `qr_image_url` 缺失，准确 instruction 必须改为：说明本次没有可展示二维码，发送金额与 `handoff.url`，明确不要调用 `present_files`，然后遵守相同停止和付款证明规则。
+
+OpenClaw 的 Host/Target 校验必须发生在读取 execution 后、创建 Checkout 前；校验失败不能调用 Checkout 创建接口。Telegram `agent_action` 的 URL action 使用 Checkout URL，callback 只包含 Checkout ID，不包含 display token，也不是付款证明。

package/docs/cli-reference/commands/services/events.md

@@ -72,4 +72,4 @@ CLI 只投影：`sequence`、`type`、`status`、`phase`、可选 `capability_id
 
 ## Agent Type / Host
 
-五种正式 Agent Type 的事件字段、鉴权和 redaction 完全相同；Host 不影响可见性，也不产生 handoff。
+七种正式 Agent Type 的事件字段、鉴权和 redaction 完全相同；Host 不影响可见性，也不产生 handoff。

package/docs/cli-reference/commands/services/get.md

@@ -65,4 +65,4 @@ execution 不存在或不属于当前身份时保留不透明 `not_found`，只
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 的状态、timeline、instruction 和 next 相同。本命令没有二维码或 Host handoff。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 的状态、timeline、instruction 和 next 相同。本命令没有二维码或 Host handoff。

package/docs/cli-reference/commands/services/index.md

@@ -44,4 +44,4 @@ itpay services --help
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 共享状态机；Agent Type 只影响身份归属和 Host instruction，不允许影响 quota 规则或服务能力。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 共享状态机；Agent Type 只影响身份归属和 Host instruction，不允许影响 quota 规则或服务能力。

package/docs/cli-reference/commands/services/invoke.md

@@ -152,4 +152,4 @@ Provider 已收到请求时，Backend 返回同一 Execution 的权威调用和
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 的 safe result 一致。instruction 可以适配对话表述，但不得隐藏 quota、价格或 schema 错误。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 的 safe result 一致。instruction 可以适配对话表述，但不得隐藏 quota、价格或 schema 错误。

package/docs/cli-reference/commands/services/list.md

@@ -60,4 +60,4 @@ itpay services list [--limit <number>] [--json]
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 返回相同列表格式；Agent instance 权限决定可见范围。本命令没有 Host handoff。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 返回相同列表格式；Agent instance 权限决定可见范围。本命令没有 Host handoff。

package/docs/cli-reference/commands/services/read-result.md

@@ -97,4 +97,4 @@ itpay services next <id> --json
 
 ## Agent Type / Host
 
-同一 Buyer account 下已登记的 `codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 可按政策领取同一订单授权；每个类型仍需自己的有效 Device Authority。五种类型返回相同字段、TTL 和错误，不因 Host 扩大 grant scope。
+同一 Buyer account 下已登记的 `codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 可按政策领取同一订单授权；每个类型仍需自己的有效 Device Authority。七种类型返回相同字段、TTL 和错误，不因 Host 扩大 grant scope。

package/docs/cli-reference/conventions.md

@@ -6,6 +6,12 @@
 
 CLI 输出是给 Agent 执行的协议，不是后端 DTO 的调试转储。默认输出适合人阅读；`--json` 使用同一语义的稳定机器合同。调试事实只由明确的诊断命令返回。
 
+## 命令变更交付顺序
+
+任何命令行为或 JSON 合同变更都必须先更新对应 CLI reference 和打包 Agent 文档，再从文档补测试和实现代码。最后实际执行文档中的命令，只标准化动态 ID、token、签名 URL 和时间戳，逐字段核对输出。
+
+实际输出不符合文档时先修实现。若产品合同确实要变，必须先重新修改并审查文档，不能用事后改文档掩盖实现偏差。
+
 ## 标准 JSON 外壳
 
 ```json
@@ -74,7 +80,7 @@ next: <one command>
 - `device_state_unwritable` 表示当前运行环境不能可靠持久化 `~/.itpay-v3`；保持同一 Agent Type 与 CLI/Node launcher，恢复 Host 写权限后重试原命令，不得手工造 lock、删除身份或换运行时碰运气。
 - WorkBuddy 在运行会持久化 `~/.itpay-v3` 的 ItPay Bash 命令前，必须把 Shell 工具参数 `dangerouslyDisableSandbox` 设为 `true`。若用户拒绝该权限，命令尚未执行：停止并报告，不得切换 Node、删除 identity、手工处理 lock 或换 Agent Type。
 - `provider_input_rejected` 只表示 Provider 明确声明输入无效；`provider_contract_mismatch` 表示响应无法按已发布契约解释，绝不能归咎于用户输入。两者都必须停止且没有自动 recovery。
-- `backend_contract_incompatible` 只有在 Backend 返回合法 `minimum_cli_version` 时才能提供一个精确的 `npm install -g @itpay/cli@<version>` recovery。不得使用 `latest`、解析 message 猜版本或继续任何业务命令；升级后必须先用 `itpay --version` 核对完全一致，再重新运行 `readyz`。
+- `backend_contract_incompatible` 只有在 Backend 返回合法 `minimum_cli_version` 时才能提供升级 recovery。npm 分发返回精确的 `npm install -g @itpay/cli@<version>`；平台 bundle 返回该平台的 Skill/plugin 更新动作。不得使用 `latest`、解析 message 猜版本或继续任何业务命令；升级后必须先用 `itpay --version` 核对完全一致，再重新运行 `readyz`。
 
 ## Instruction 模板
 

package/docs/skill-bundle-rollout/02-platform-bundle-repositories.md

@@ -1,6 +1,6 @@
 # 核心任务二：多平台 Bundle Skill 仓库与自动同步
 
-状态：待实施
+状态：首批平台已实施
 
 ## 1. Current State
 
@@ -31,7 +31,7 @@ CLI 发布后：
 
 ```text
 @itpay/cli@X.Y.Z 发布成功
-  -> 通知四个平台仓库
+  -> 各平台仓库定时读取 npm dist-tags.latest
   -> 下载精确 X.Y.Z 和 npm integrity
   -> 安装精确 production dependencies
   -> 生成 bundle 和 lock
@@ -126,16 +126,20 @@ itpay-skill-workbuddy/
 
 ### 第一阶段产物
 
-第一阶段使用“vendored Node bundle”，不增加打包器：
+平台按审核环境选择现有的两种构建格式：
 
 ```text
-vendor/itpay-cli/package/       npm 包内容
-vendor/itpay-cli/node_modules/  仅 production dependencies
-bin/itpay                       平台薄启动器
-bundle.lock.json                来源证明
+npm-tree:
+  vendor/itpay-cli/package/       npm 包内容
+  vendor/itpay-cli/node_modules/  仅 production dependencies
+
+single-file-esm:
+  vendor/itpay-cli/itpay-cli.bundle.mjs
+  vendor/itpay-cli/docs/agent/buyer/
+  vendor/itpay-cli/licenses/
 ```
 
-运行时不得联网安装。宿主必须已有 Node.js 18+。如果某平台审核环境没有 Node，再单独启动“standalone executable”任务；不要在还没有失败证据时提前维护多架构二进制。
+WorkBuddy 和 OpenClaw 使用 `single-file-esm`，上传包不得包含任何 `node_modules`。npm 依赖只允许出现在 CI 临时构建目录；运行时不得联网安装。宿主必须已有 Node.js 18+。如果某平台审核环境没有 Node，再单独启动“standalone executable”任务；不要在还没有失败证据时提前维护多架构二进制。
 
 ### `bundle.lock.json`
 
@@ -209,25 +213,18 @@ bundle 不包含凭据、.env、~/.itpay-v3 或 npm token
 
 ### Step 4：CLI 发布后创建同步 PR
 
-修改 CLI 主仓库现有 npm CD：只有 npm publish 成功或确认该 commit 已发布后，才向平台仓库发送带以下字段的事件：
+CLI 主仓库在 `main` 提供 reusable workflow。各平台仓库每小时错峰运行 caller workflow，并可手动触发；npm `dist-tags.latest` 或请求的 bundle format 与当前 `bundle.lock.json` 不同时更新。平台仓库自身的 `GITHUB_TOKEN` 写入本仓库，因此不需要跨仓 PAT，也不会在 CLI 发布失败时提前同步未发布版本。
 
-```json
-{
-  "version": "2.0.14",
-  "npm_integrity": "sha512-...",
-  "source_git_sha": "..."
-}
-```
-
-平台仓库收到事件后：
+检测到新版本后：
 
 - 重新生成 bundle；
 - 更新 manifest 版本、lock、changelog；
 - 跑全套测试；
-- 创建 `sync @itpay/cli X.Y.Z` PR；
+- 对启用 Skill 差异跟踪的平台，比较旧、新 `sourceGitSha` 的中心 `skills/itpay/SKILL.md`；有差异时创建 Draft PR、附 diff 和人工合并清单，但不覆盖平台 Skill；
+- 创建或刷新 `automation/itpay-cli-X.Y.Z` 分支和同步 PR；
 - PR 描述列出 CLI commit、integrity、平台测试和是否需要商店重新审核。
 
-增加每日一次的版本漂移检查作为丢失事件的兜底，只报警或补 PR，不直接发布。
+同步 workflow 只开 PR，不合并、不打 tag、不发布平台商店版本。
 
 依赖：Step 3。
 
@@ -247,7 +244,7 @@ CLI 业务 API：无。
 新增发布合同：
 
 - `bundle.lock.json` schema。
-- CLI release dispatch payload。
+- CLI reusable workflow 与各平台 caller workflow。
 - 每个平台 manifest 和平台版本。
 
 CLI 版本和平台包版本第一阶段保持相同，减少映射成本。若以后平台仅修改说明而 CLI 未变，再引入独立的 `pluginVersion`，同时保留 `cliVersion`；现在不提前增加双版本系统。
@@ -272,11 +269,11 @@ CLI 版本和平台包版本第一阶段保持相同，减少映射成本。若
 ## 9. Risks / Uncertainties
 
 - OpenAI Skill 沙箱是否提供满足要求的 Node 运行时不能作为稳定合同；ChatGPT 路径应以远程 MCP 为主。
-- vendored `node_modules` 会增大包体，但当前依赖很少，先以真实平台大小限制验证，不提前引入 bundler。
+- `single-file-esm` 仍依赖宿主 Node.js 18+；未来引入原生 Node addon 时需要重新验证 bundling。
 - 四个仓库意味着四套审核节奏，但不意味着四套 CLI 业务实现。
 - WorkBuddy 公共 SkillHub 提交通道未公开，自动化只能先生成可上传包。
 - 平台安全扫描可能拒绝支付或可执行 bundle；拒绝原因应反馈到相应平台仓库，不改变其他平台已通过版本。
 
 ## 10. Checkpoint
 
-仓库创建和跨仓凭据配置属于外部状态操作。实施到该步骤时需要仓库组织名、创建权限和最小权限 GitHub App/PAT；在此之前可以完成生成器、模板和本地验证。
+首批仓库、生成器和无跨仓凭据的同步 workflow 已完成。剩余 checkpoint 是各平台审核与人工发布；这些步骤不由同步 workflow 自动执行。

package/docs/skill-bundle-rollout/03-platform-publishing.md

@@ -231,7 +231,7 @@ WorkBuddy 官方文档确认：
 
 ### 制作与本地上传
 
-1. 生成 `itpay-skill-workbuddy` 的自包含 Node bundle。
+1. 生成 `itpay-skill-workbuddy` 的 `single-file-esm` Node bundle；上传包不得包含 `node_modules`，也不得在运行时执行 npm。
 2. `SKILL.md` frontmatter 提供清晰名称、描述和触发条件。
 3. 声明：执行本地命令、连接 `app.itpay.ai`、写入 owner-only `~/.itpay-v3` Device 状态、显示外部 Checkout。
 4. 不申请屏幕控制、任意目录写入或与 ItPay 无关的网络权限。
@@ -239,6 +239,7 @@ WorkBuddy 官方文档确认：
 6. 在 WorkBuddy：技能 -> 添加技能 -> 上传技能，选择技能包。
 7. 检查安全扫描结果和权限提示，分别在默认权限、完全访问权限下验证；默认权限必须能够通过用户确认完成流程。
 8. 验证 macOS 和 Windows，尤其是 Node 可用性、中文用户名、路径空格、持久 HOME 和版本更新。
+9. CLI 同步 PR 若附带中心 Skill 差异，先人工合并新增业务规则并保留 WorkBuddy 权限、QR 和 sandbox 规则，通过平台测试后再把 Draft PR 标记为 ready。
 
 ### SkillHub 公共发布