@itpay/cli 2.0.14 → 2.0.16

package/dist/src/render/telegram.js

@@ -28,14 +28,49 @@ function buttonsFor(plan) {
             : []),
     ];
 }
+function nativeButton(button) {
+    if (button.kind === "url") {
+        return { label: button.label, action: { type: "url", url: button.url ?? "" } };
+    }
+    const value = button.intent === "check_checkout_status"
+        ? `itp:checkout:${button.ref ?? ""}`
+        : `itp:${button.intent ?? "callback"}:${button.ref ?? ""}`;
+    return { label: button.label, action: { type: "callback", value } };
+}
 function format(plan) {
     return plan.kind === "payment_qr" ? "photo_text_inline_buttons" : "text_inline_buttons";
 }
 export function renderTelegram(plan, options) {
     const out = options.output ?? ((line) => process.stdout.write(line));
-    const buttons = buttonsFor(plan);
+    const agentAction = buildOpenClawTelegramAction(plan, options.target);
+    const presentation = agentAction.arguments.presentation;
+    const media = collectTelegramMedia(plan);
+    const text = agentAction.arguments.message;
+    const openclawMessage = {
+        command: [
+            "openclaw",
+            "message",
+            "send",
+            "--channel",
+            "telegram",
+            "--target",
+            options.target,
+            "--message",
+            text,
+            ...(media.length > 0 ? ["--media", media[0].url] : []),
+            "--presentation",
+            JSON.stringify(presentation),
+        ],
+        // Hint: agents that cannot run openclaw must stop and tell the user
+        // they lack the native Telegram buttons tool — never downgrade.
+        if_unavailable: "Current agent cannot run `openclaw message send`. Stop and tell the user the native Telegram inline-button tool is missing; do not downgrade to a markdown table or plain link.",
+    };
+    out(JSON.stringify({ presentation, agent_action: agentAction, openclaw_message: openclawMessage }, null, 2) + "\n");
+}
+export function buildOpenClawTelegramAction(plan, target) {
+    const buttons = buttonsFor(plan).map(nativeButton);
     const media = collectTelegramMedia(plan);
-    const text = plan.kind === "payment_qr"
+    const message = plan.kind === "payment_qr"
         ? `ItPay payment QR — ${plan.summary}`
         : plan.kind === "auth_qr"
             ? `ItPay auth required — ${plan.summary}`
@@ -43,12 +78,12 @@ export function renderTelegram(plan, options) {
     const presentation = {
         format: format(plan),
         media,
-        text,
+        text: message,
         links: plan.platform.links,
         buttons,
         interactions: plan.platform.interactions ?? [],
         blocks: [
-            { type: "text", text },
+            { type: "text", text: message },
             ...(media.length > 0 ? [{ type: "image", url: media[0].url }] : []),
             { type: "buttons", buttons },
         ],
@@ -64,31 +99,22 @@ export function renderTelegram(plan, options) {
                     must_render_reason: plan.ideImageAttach.mustRenderReason,
                     ...(plan.ideImageAttach.error ? { error: plan.ideImageAttach.error } : {}),
                     action: "agent_must_render_into_ide_chat",
-                    instructions: ideImageAttachBlock(plan.ideImageAttach).filter((l) => l.length > 0),
+                    instructions: ideImageAttachBlock(plan.ideImageAttach).filter((line) => line.length > 0),
                 },
             }
             : {}),
     };
-    const openclawMessage = {
-        command: [
-            "openclaw",
-            "message",
-            "send",
-            "--channel",
-            "telegram",
-            "--target",
-            options.target,
-            "--message",
-            text,
-            ...(media.length > 0 ? ["--media", media[0].url] : []),
-            "--presentation",
-            JSON.stringify(presentation),
-        ],
-        // Hint: agents that cannot run openclaw must stop and tell the user
-        // they lack the native Telegram buttons tool — never downgrade.
-        if_unavailable: "Current agent cannot run `openclaw message send`. Stop and tell the user the native Telegram inline-button tool is missing; do not downgrade to a markdown table or plain link.",
+    return {
+        tool: "message",
+        arguments: {
+            action: "send",
+            channel: "telegram",
+            target,
+            message,
+            ...(media[0]?.url ? { media: media[0].url } : {}),
+            presentation,
+        },
     };
-    out(JSON.stringify({ presentation, openclaw_message: openclawMessage }, null, 2) + "\n");
 }
 export function renderTelegramInteraction(request, options) {
     const out = options.output ?? ((line) => process.stdout.write(line));
@@ -97,7 +123,7 @@ export function renderTelegramInteraction(request, options) {
         mimeType: item.mimeType ?? "image/png",
     }));
     const buttons = request.kind === "selector"
-        ? request.options.map((option) => selectorButton(request.id, option))
+        ? request.options.map((option) => nativeButton(selectorButton(request.id, option)))
         : [];
     const text = `${request.title} — ${request.prompt}`;
     const presentation = {

package/dist/src/state/client_context.js

@@ -62,6 +62,8 @@ export function defaultHostForAgentType(agentType) {
         return "claude-code";
     if (normalized === "workbuddy")
         return "plain-chat";
+    if (normalized === "openclaw")
+        return undefined;
     return "terminal";
 }
 export function validateContext(host, target) {

package/dist/src/state/config.js

@@ -1,5 +1,5 @@
-// CLI configuration loader. The production Backend is pinned to app.itpay.ai;
-// environment variables configure only non-Backend runtime details. Checkout
+// CLI configuration loader. Production defaults to app.itpay.ai; the only
+// allowed override is the official dev Backend. Checkout
 // display-token persistence belongs to the cart session file, protected with
 // owner-only permissions. Provider secrets are explicitly out of scope here.
 import { homedir } from "node:os";
@@ -11,21 +11,61 @@ import { declaredAgentType } from "./agent_type.js";
 import { DeviceAuthority } from "./device_authority.js";
 import { OperationJournal } from "./operation_journal.js";
 export const DEFAULT_BASE_URL = "https://app.itpay.ai";
-export const CLI_VERSION = "2.0.14";
+export const DEV_BASE_URL = "https://dev.itpay.ai";
+export const CLI_VERSION = "2.0.16";
 export const API_CONTRACT_REVISION = "sha256:7f4c40b082292bf823631bcd37d452f4a8537153e30636d5eb3a2b24a77ce602";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";
 const OPERATION_JOURNAL_FILENAME = "operations.json";
+export function cliDistribution(env = process.env) {
+    if (env.ITPAY_DISTRIBUTION === "openclaw-skill-bundle")
+        return "openclaw-skill-bundle";
+    if (env.ITPAY_DISTRIBUTION === "kimi-plugin-bundle")
+        return "kimi-plugin-bundle";
+    return "npm";
+}
+export class BackendOverrideError extends Error {
+    code = "backend_override_forbidden";
+    constructor() {
+        super(`ITPAY_BACKEND_URL only supports ${DEFAULT_BASE_URL} or ${DEV_BASE_URL}`);
+        this.name = "BackendOverrideError";
+    }
+}
+export function resolveBackendURL(env = process.env) {
+    const requested = env.ITPAY_BACKEND_URL?.trim();
+    if (!requested || requested === DEFAULT_BASE_URL || requested === `${DEFAULT_BASE_URL}/`)
+        return DEFAULT_BASE_URL;
+    if (requested === DEV_BASE_URL || requested === `${DEV_BASE_URL}/`)
+        return DEV_BASE_URL;
+    throw new BackendOverrideError();
+}
+export function qualifyBackendCommand(command, env = process.env) {
+    const requested = env.ITPAY_BACKEND_URL?.trim();
+    if (requested !== DEV_BASE_URL && requested !== `${DEV_BASE_URL}/`)
+        return command;
+    if (!command.startsWith("itpay ") || command.startsWith(`ITPAY_BACKEND_URL=${DEV_BASE_URL} `))
+        return command;
+    return `ITPAY_BACKEND_URL=${DEV_BASE_URL} ${command}`;
+}
+function stateFilename(filename, baseURL) {
+    if (baseURL !== DEV_BASE_URL)
+        return filename;
+    const dot = filename.lastIndexOf(".");
+    return dot < 0 ? `${filename}.dev` : `${filename.slice(0, dot)}.dev${filename.slice(dot)}`;
+}
+function stateDir(env) {
+    return resolve(env.HOME || homedir(), CART_SESSION_DEFAULT_DIR);
+}
 export function cartSessionPath(env = process.env) {
     if (env.ITPAY_CART_SESSION_PATH) {
         return resolve(env.ITPAY_CART_SESSION_PATH);
     }
-    const dir = resolve(homedir(), CART_SESSION_DEFAULT_DIR);
+    const dir = stateDir(env);
     mkdirSync(dir, { recursive: true });
-    return resolve(dir, CART_SESSION_FILENAME);
+    return resolve(dir, stateFilename(CART_SESSION_FILENAME, resolveBackendURL(env)));
 }
 export function loadConfig(env = process.env) {
-    const baseURL = DEFAULT_BASE_URL;
+    const baseURL = resolveBackendURL(env);
     const bearerToken = env.ITPAY_BEARER_TOKEN || undefined;
     const agentType = declaredAgentType(env);
     const checkoutCurrency = env.ITPAY_CURRENCY || "CNY";
@@ -34,10 +74,11 @@ export function loadConfig(env = process.env) {
     const ideImageDirOverride = env.ITPAY_IDE_IMAGE_DIR_OVERRIDE;
     return {
         baseURL,
+        environment: baseURL === DEV_BASE_URL ? "development" : "production",
         ...(agentType ? { agentType } : {}),
         checkoutCurrency,
         idempotencyKey,
-        ...(!env.ITPAY_IDEMPOTENCY_KEY ? { operationJournal: new OperationJournal(resolve(homedir(), CART_SESSION_DEFAULT_DIR, OPERATION_JOURNAL_FILENAME)) } : {}),
+        ...(!env.ITPAY_IDEMPOTENCY_KEY ? { operationJournal: new OperationJournal(resolve(stateDir(env), stateFilename(OPERATION_JOURNAL_FILENAME, baseURL))) } : {}),
         ideImageAttach,
         ...(ideImageDirOverride ? { ideImageDirOverride } : {}),
         ...(bearerToken ? { bearerToken } : {}),

package/docs/agent/buyer/identity-and-sessions.json

@@ -4,16 +4,16 @@
   "product_scope": "itpay is the single public CLI entry point, and $itpay is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are buy and sell: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.",
   "topic": "identity-and-sessions",
   "title": "Device Identity And Session Recovery",
-  "purpose": "Explain stable local identity, the fixed app.itpay.ai production registration, Agent Type instances, and bounded automatic session recovery.",
+  "purpose": "Explain stable local identity, official Backend-scoped registrations, Agent Type instances, and bounded automatic session recovery.",
   "when_to_use": [
     "A different Agent window or runtime starts using an existing CLI installation.",
     "The CLI reports device_state_unwritable, or the Backend reports agent_identity_required, agent_device_session_required, or agent_device_revoked.",
-    "An operator confirms that the app.itpay.ai Device registration database was reset."
+    "An operator confirms that the currently selected official Backend registration database was reset."
   ],
   "identity_model": {
     "local_key": "One owner-only Ed25519 private key for the local installation.",
-    "backend_registration": "One production Device registration for https://app.itpay.ai; runtime environment variables cannot redirect the CLI.",
-    "agent_instance": "One instance per agent_type under the production registration; same-type windows and chats reuse it.",
+    "backend_registration": "One registration per official Backend: app.itpay.ai by default and dev.itpay.ai only with the exact test override.",
+    "agent_instance": "One instance per agent_type under each Backend registration; same-type windows and chats reuse it.",
     "presentation": "Host and target route output only and never identify the Agent or provide business input."
   },
   "automatic_recovery": [
@@ -34,27 +34,27 @@
       "success_signal": "the full Skill is returned and next keeps the same Agent Type"
     },
     {
-      "intent": "confirm app.itpay.ai is available",
+      "intent": "confirm the selected official Backend is available",
       "command": "itpay --agent-type <agent_type> readyz --json",
       "success_signal": "Backend is available and onboarding returns to the Skill"
     },
     {
-      "intent": "recover after an operator-confirmed reset of the app.itpay.ai Device registration database",
+      "intent": "recover after an operator-confirmed reset of the selected official Backend registration database",
       "command": "itpay --agent-type <agent_type> device recover --confirm-backend-reset --json",
-      "success_signal": "only the app.itpay.ai registration is removed and the private key remains"
+      "success_signal": "only the selected Backend registration is removed and the private key and other Backend registration remain"
     }
   ],
   "agent_rules": [
     "Use the real runtime type and keep it stable across every command in the flow.",
     "Keep the same CLI/Node launcher and Host-approved permission context for the whole flow.",
     "Treat a new window, chat, task, or process of the same runtime as the same Agent Type, not a new identity.",
-    "Expect all production CLI traffic to use https://app.itpay.ai; do not set or suggest a Backend URL override.",
-    "After automatic recovery fails, stop and report the exact code, app.itpay.ai, Agent Type, and command family without exposing private keys or tokens."
+    "Expect production traffic to use https://app.itpay.ai. Use https://dev.itpay.ai only for an explicit test and keep the complete returned Backend-prefixed command for that entire flow.",
+    "After automatic recovery fails, stop and report the exact code, selected official Backend, Agent Type, and command family without exposing private keys or tokens."
   ],
   "forbidden": [
     "Do not delete ~/.itpay-v3, rotate the key, switch Agent Type, or repeatedly retry to obtain fresh quota.",
     "Do not use device recover for session expiry, revocation, quota recovery, or an unconfirmed Backend failure.",
-    "Do not redirect the CLI to dev, test, local, or any non-app.itpay.ai Backend.",
+    "Do not redirect the CLI to test, local, an IP, or any custom Backend; only the exact official dev.itpay.ai test override is allowed.",
     "Do not use --target as identity or service input."
   ],
   "next_docs": [

package/docs/agent/buyer/install-and-setup.json

@@ -4,7 +4,7 @@
   "product_scope": "itpay is the single public CLI entry point, and $itpay is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are buy and sell: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.",
   "topic": "install-and-setup",
   "title": "Install And Identify The ItPay Agent Runtime",
-  "purpose": "Install the CLI, load the complete ItPay Skill, and select one stable Agent Type without confusing identity, Backend, Host, target, or chat window.",
+  "purpose": "Load the complete ItPay Skill and select one stable Agent Type without confusing distribution, identity, Backend, Host, target, or chat window.",
   "when_to_use": [
     "The CLI is being installed or upgraded.",
     "The agent needs to confirm its stable runtime identity and default output Host."
@@ -23,7 +23,7 @@
     {
       "intent": "list supported Agent Types",
       "command": "itpay install --json",
-      "success_signal": "status is install_targets and exactly five agent_type/default_host pairs are returned"
+      "success_signal": "status is install_targets and exactly seven supported Agent Type definitions are returned"
     },
     {
       "intent": "read setup for the real runtime",
@@ -32,21 +32,20 @@
     }
   ],
   "agent_rules": [
-    "Install with npm install -g @itpay/cli.",
-    "The production Backend is fixed to https://app.itpay.ai and cannot be redirected by runtime environment variables.",
-    "If backend_contract_incompatible includes result.required_cli_version, stop all ItPay business commands and run only the exact npm install recovery returned by the CLI; never replace its version with latest.",
+    "Use the CLI distribution already provided by the current npm package, Skill, or plugin; install only through that distribution's own instructions.",
+    "Production defaults to https://app.itpay.ai. Testing may set ITPAY_BACKEND_URL to the exact official URL https://dev.itpay.ai; no other Backend is allowed.",
+    "If backend_contract_incompatible includes result.required_cli_version, stop all ItPay business commands and use only the exact distribution-specific update recovery returned by the CLI; never replace its version with latest.",
     "After upgrading, require itpay --version to equal result.required_cli_version before running readyz again; never change Agent Type or Device identity to recover compatibility.",
-    "The production Backend is fixed to https://app.itpay.ai and cannot be redirected by runtime environment variables.",
-    "Use one exact type: codex-desktop, codex-cli, claude-code-desktop, claude-code-cli, or workbuddy.",
-    "One local private key is reused with the https://app.itpay.ai production Device registration and quota lineage.",
-    "Within the production Backend registration, each Agent Type has one Agent Instance; all windows and chats of the same type reuse it.",
-    "Agent Type identifies the runtime. Host controls rendering and target only identifies a presentation destination.",
+    "Use one exact type: codex-desktop, codex-cli, claude-code-desktop, claude-code-cli, workbuddy, kimi-code, or openclaw.",
+    "One local private key is reused, while Device registrations and quota lineage remain separate for app.itpay.ai and dev.itpay.ai.",
+    "Within each official Backend registration, each Agent Type has one Agent Instance; all windows and chats of the same type reuse it.",
+    "Agent Type identifies the runtime. Host controls rendering and target only identifies a presentation destination. OpenClaw requires an explicit Host and IM target; Kimi Code uses the standard terminal CLI contract.",
     "Keep the exact Agent Type in every next or recovery command; do not fall back to a type previously used by another runtime.",
     "Do not change Agent Type or rotate local identity to reset quota or recover a failed command."
   ],
   "forbidden": [
     "Do not use codex, terminal, claude-code, or plain-chat as Agent Types.",
-    "Do not set or suggest a Backend URL override; production CLI traffic always targets https://app.itpay.ai.",
+    "Do not set or suggest any Backend except the default https://app.itpay.ai or the exact test override https://dev.itpay.ai.",
     "Do not claim that install writes host configuration or registers a device; it only prints instructions.",
     "Do not create a new identity for a different window, task, chat, or process of the same Agent Type."
   ],
@@ -67,6 +66,8 @@
     "backend",
     "codex",
     "claude code",
-    "workbuddy"
+    "workbuddy",
+    "kimi code",
+    "openclaw"
   ]
 }

package/docs/agent/buyer/payment-flow.json

@@ -32,6 +32,7 @@
     "Before creating a single-Service Checkout, send the exact price confirmation requested by the current instruction, stop, and wait for explicit human agreement.",
     "After presenting a Checkout, stop. Run the returned next.command only after the human completes the payment action or asks to query the same Checkout.",
     "For workbuddy with plain-chat, present the returned HTTPS QR with present_files exactly as instructed; presentation failure falls back only to handoff.url and never creates another payment resource.",
+    "For openclaw with telegram, execute the returned native message action using the current trusted target. For any other explicit OpenClaw Host, show the returned HTTPS QR image and Checkout URL.",
     "Payment is verified only by Backend Checkout or Order state, never by QR rendering, redirect, or user claim.",
     "A terminal payment state must never display another payment handoff."
   ],

package/docs/agent/buyer/quickstart.json

@@ -12,7 +12,7 @@
   "required_state": {
     "needs": [
       "the real supported Agent Type",
-      "the fixed production Backend https://app.itpay.ai"
+      "one official Backend: production https://app.itpay.ai by default, or explicit test https://dev.itpay.ai"
     ],
     "must_not_need": [
       "Admin access",
@@ -22,7 +22,7 @@
   },
   "commands": [
     {
-      "intent": "verify fixed production Backend availability",
+      "intent": "verify the selected official Backend availability",
       "command": "itpay --agent-type <agent_type> readyz --json",
       "success_signal": "status is ready and next points to the complete packaged ItPay Skill"
     },
@@ -57,7 +57,9 @@
     "Treat result as current facts, instruction as how to use those facts, next as the preferred executable action, and recovery as exceptional paths.",
     "Run one state-changing command at a time. Treat next.command as the preferred continuation: execute it unchanged after filling required user data only when the current result has not already satisfied the user's goal.",
     "Keep the same explicit Agent Type through next and recovery commands; same-type windows reuse one Backend Agent Instance.",
+    "When testing dev, execute every returned command unchanged so its ITPAY_BACKEND_URL=https://dev.itpay.ai prefix is preserved.",
     "Use --target only for a Host presentation destination. Put capability business values in --input key=value exactly as required by the schema.",
+    "OpenClaw must pass the current entry as --host and an IM destination as --target. Kimi Code follows the standard terminal CLI flow.",
     "Start a separate Service Execution for each independent service intent; quota remains shared according to Backend identity policy.",
     "Ask the user for required email or contact values and explain their purpose; never invent them.",
     "Agent-visible delivery is returned by services next. Protected delivery is read only by services read-result while a human grant is active.",

package/docs/agent/buyer/render-hosts.json

@@ -34,6 +34,18 @@
       "agent_type": "workbuddy",
       "default_host": "plain-chat",
       "responsibility": "when handoff.qr_image_url exists, use its exact HTTPS value as the only files element in present_files; otherwise send the Checkout URL without calling present_files; show the amount and stop"
+    },
+    {
+      "agent_type": "kimi-code",
+      "default_host": "terminal",
+      "responsibility": "use the standard CLI terminal QR and Checkout URL"
+    },
+    {
+      "agent_type": "openclaw",
+      "default_host": null,
+      "host_required": true,
+      "native_hosts": ["telegram"],
+      "responsibility": "pass the current entry explicitly; for Telegram execute handoff.agent_action with the current target, otherwise show the returned HTTPS QR image and Checkout URL"
     }
   ],
   "commands": [
@@ -53,7 +65,8 @@
     "A local QR path is not visible until a desktop Agent attaches or renders that file on the human-facing surface; WorkBuddy never receives a local QR path.",
     "For workbuddy with plain-chat, call present_files exactly as the returned instruction says. If it fails, send only handoff.url, report that the preview did not open, and stop.",
     "Do not claim the handoff was shown until both a usable payment image or QR and the Checkout URL are visible.",
-    "IM Hosts that require a target must receive --target; the initial five Agent Types currently default to desktop, terminal, or plain-chat Hosts."
+    "IM Hosts that require a target must receive --target before Checkout creation. OpenClaw has no default Host; Kimi Code uses terminal.",
+    "OpenClaw Telegram typed callback actions carry only the Checkout ID, never a display token, and never prove payment."
   ],
   "forbidden": [
     "Do not expose display tokens separately from the tokenized Checkout handoff.",
@@ -74,6 +87,9 @@
     "markdown",
     "terminal",
     "desktop",
-    "workbuddy"
+    "workbuddy",
+    "kimi code",
+    "openclaw",
+    "telegram"
   ]
 }

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

@@ -18,7 +18,7 @@ itpay cart remove --local --variant <catalog_variant_id> --offer <offer_id> [--j
 
 | 参数 | 必填 | 说明 |
 | --- | --- | --- |
-| `--line <cart_item_id>` | 否 | canonical Cart line；省略时使用固定 `https://app.itpay.ai` 后端下最后保存的 line。 |
+| `--line <cart_item_id>` | 否 | canonical Cart line；省略时使用当前官方 Backend 对应本地状态中最后保存的 line。 |
 | `--local` | 否 | 只修改显式本地草稿，不请求 Backend。 |
 | `--variant <catalog_variant_id>` | local 时是 | 与 `--offer` 一起标识本地草稿 line。 |
 | `--offer <offer_id>` | local 时是 | 与 `--variant` 一起标识本地草稿 line。 |
@@ -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/device.md

@@ -10,6 +10,6 @@
 itpay --agent-type <agent_type> device recover --confirm-backend-reset --json
 ```
 
-命令只作用于固定生产后端 `https://app.itpay.ai` 的 Device registration，并保留本地 Ed25519 私钥、Cart 和业务资源。CLI 不接受 Backend URL 覆盖。该命令不访问 Backend、不自动创建新身份；返回的只读 `services list` 是重新登记入口。
+命令只作用于当前官方 Backend 的 Device registration，并保留本地 Ed25519 私钥、Cart 和业务资源。默认是 `https://app.itpay.ai`；显式测试可使用准确的 `ITPAY_BACKEND_URL=https://dev.itpay.ai`。该命令不访问 Backend、不自动创建新身份；返回的只读 `services list` 会保留同一 Backend，是重新登记入口。
 
 缺少确认参数返回 `backend_reset_confirmation_required`。普通 session 失效由 CLI 自动续期；revoked、quota、权限或未知 Backend 故障不得使用本命令。所有 Agent Type 使用相同输入和输出合同。

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 匹配的部分。