@itpay/cli 2.0.14 → 2.0.16

package/README.md

@@ -15,7 +15,7 @@ itpay --agent-type codex-desktop readyz --json
 # follow next.command: typed skill show, then catalog list
 ```
 
-The production Backend is permanently pinned to `https://app.itpay.ai`. Runtime environment variables cannot redirect the CLI to another Backend.
+The CLI defaults to the production Backend `https://app.itpay.ai`. Explicit tests may set `ITPAY_BACKEND_URL=https://dev.itpay.ai`; every other Backend URL is rejected before network or local state access.
 
 ## Output Contract
 
@@ -46,11 +46,11 @@ Normative per-command contracts: [CLI Command Reference](docs/cli-reference/inde
 
 `--agent-type` identifies the stable runtime and registered Agent instance. Every returned ItPay command preserves it. Different windows or chats of the same type reuse one Agent Instance; they are not separate identities. `--host` only selects the human presentation surface, and `--target` only routes output to a Host destination. Use `itpay install <agent_type> --json` for the exact responsibility.
 
-The local installation keeps one Ed25519 private key and one production Device registration for `https://app.itpay.ai`, with one Agent Instance per Agent Type. A rejected session is renewed and the same request is retried once; revoked v2 registrations are never silently replaced.
+The local installation keeps one Ed25519 private key and a separate registration for each official Backend, with one Agent Instance per Agent Type under each registration. A rejected session is renewed and the same request is retried once; revoked v2 registrations are never silently replaced.
 
 ## Command Families
 
-- `readyz`: fixed production Backend liveness; `catalog list`: compatibility-gated discovery.
+- `readyz`: selected official Backend liveness; `catalog list`: compatibility-gated discovery.
 - `services start/invoke/action/checkout/next`: generic Service Execution flow.
 - `cart add/show/remove/clear/next`, `buy`: canonical Cart and ordinary Checkout flow.
 - `checkout`: authoritative payment and fulfillment recovery.
@@ -75,11 +75,12 @@ itpay --agent-type <agent_type> services checkout <service_execution_id> --resum
 itpay checkout --id <checkout_id> --token <display_token> --json
 ```
 
-The local `~/.itpay-v3` directory stores one owner-only signing key, the `https://app.itpay.ai` Device registration and Agent instances, idempotency operations, and recovery handles. Backend state remains authoritative. Do not delete or rotate this identity to recover quota.
+The local `~/.itpay-v3` directory stores one owner-only signing key, Backend-scoped Device registrations and Agent instances, idempotency operations, and recovery handles. Production uses `cart.json` / `operations.json`; dev uses `cart.dev.json` / `operations.dev.json`. Backend state remains authoritative. Do not delete or rotate this identity to recover quota.
 
 ## Environment
 
 - `ITPAY_AGENT_TYPE`: stable alternative to global `--agent-type`.
+- `ITPAY_BACKEND_URL`: optional test override; only the exact official URL `https://dev.itpay.ai` is accepted. Unset it for production.
 - `ITPAY_BEARER_TOKEN`: account-scoped Buyer session for account-only commands such as `orders`.
 - `ITPAY_CART_SESSION_PATH`: local recovery-state path override.
 - `ITPAY_CURRENCY`: ordinary Cart currency, default `CNY`.

package/dist/src/commands/buy.js

@@ -141,6 +141,7 @@ export async function runBuy(backend, config, options) {
             ...(qrPNGURL ? { qrPNGURL } : {}),
             ...(paymentIntent ? { paymentIntent } : {}),
             ...(options.agentType ? { agentType: options.agentType } : {}),
+            ...(options.target ? { target: options.target } : {}),
         });
         writeCommandEnvelope(envelope, { jsonOutput: true, ...(options.output ? { output: options.output } : {}) });
         return {
@@ -198,7 +199,9 @@ function buildBuyEnvelope(input) {
         platform,
         url: input.checkoutURL,
         amount,
+        plan: input.plan,
         ...(input.agentType ? { agentType: input.agentType } : {}),
+        ...(input.target ? { target: input.target } : {}),
         ...(input.qrPNGURL ? { qrImageURL: input.qrPNGURL } : {}),
         ...(input.plan.ideImageAttach?.status === "downloaded" && input.plan.ideImageAttach.localPath
             ? { localPath: input.plan.ideImageAttach.localPath }

package/dist/src/commands/checkout.js

@@ -46,7 +46,7 @@ export async function runCheckoutPresentation(backend, options) {
             ...(options.baseURL ? { baseURL: options.baseURL } : {}),
         });
     }
-    const envelope = pendingCheckoutEnvelope(presentation, checkoutURL, plan, nextCommand, options.agentType);
+    const envelope = pendingCheckoutEnvelope(presentation, checkoutURL, plan, nextCommand, options.agentType, options.target);
     const plainResult = checkoutPlainResult(envelope.result);
     if (!options.jsonOutput && platformKeyForHost(host) === "terminal") {
         plainResult.push("qr:", await renderTerminalQR(checkoutURL, "terminal"));
@@ -57,14 +57,16 @@ export async function runCheckoutPresentation(backend, options) {
         plainResult,
     });
 }
-function pendingCheckoutEnvelope(presentation, checkoutURL, plan, nextCommand, agentType) {
+function pendingCheckoutEnvelope(presentation, checkoutURL, plan, nextCommand, agentType, target) {
     const platform = platformKeyForHost(plan.host);
     const amount = formatMoney(presentation.checkout.amount_minor, presentation.checkout.currency);
     const presentationHandoff = buildCheckoutHandoff({
         platform,
         url: checkoutURL,
         amount,
+        plan,
         ...(agentType ? { agentType } : {}),
+        ...(target ? { target } : {}),
         ...(plan.preferredQRSources[0] ? { qrImageURL: plan.preferredQRSources[0] } : {}),
         ...(plan.ideImageAttach?.status === "downloaded" && plan.ideImageAttach.localPath
             ? { localPath: plan.ideImageAttach.localPath }

package/dist/src/commands/checkout_handoff.js

@@ -1,3 +1,4 @@
+import { buildOpenClawTelegramAction } from "../render/telegram.js";
 export function shouldPrepareLocalCheckoutImage(platform) {
     return platform === "markdown";
 }
@@ -15,6 +16,12 @@ export function buildCheckoutHandoff(input) {
     else if (input.platform === "plain_chat" && input.qrImageURL) {
         handoff.qr_image_url = input.qrImageURL;
     }
+    else if (input.platform === "telegram" && input.qrImageURL) {
+        handoff.qr_image_url = input.qrImageURL;
+    }
+    if (input.agentType?.trim().toLowerCase() === "openclaw" && input.platform === "telegram" && input.plan && input.target) {
+        handoff.agent_action = buildOpenClawTelegramAction(input.plan, input.target);
+    }
     return {
         handoff,
         instruction: checkoutHandoffInstruction(input.agentType, input.platform, input.amount, Boolean(input.qrImageURL)),

package/dist/src/commands/compatibility.js

@@ -14,7 +14,6 @@ export async function requirePlatformCompatibility(backend) {
         maximum_cli_major: platform.maximum_cli_major,
         platform_revision: platform.platform_revision,
         api_contract_revision: platform.api_contract_revision,
-        upgrade_command: `npm install -g @itpay/cli@${platform.minimum_cli_version}`,
     }, "CLI is incompatible with the active ItPay platform release");
 }
 function compareVersions(left, right) {

package/dist/src/commands/guidance.js

@@ -1,6 +1,7 @@
 import { HttpError } from "../client/http.js";
 import { resolveOutput } from "../render/sink.js";
 import { declaredAgentType, qualifyItPayCommand } from "../state/agent_type.js";
+import { qualifyBackendCommand } from "../state/config.js";
 export function isTerminalServiceExecutionStatus(status) {
     return status === "failed" || status === "refunded" || status === "cancelled";
 }
@@ -84,7 +85,7 @@ export function printAgentGuidance(guidance, output) {
         out("next actions:\n");
         for (const action of guidance.next_actions) {
             out(`  - ${action.label}\n`);
-            out(`    ${qualifyItPayCommand(action.command, agentType)}\n`);
+            out(`    ${qualifyBackendCommand(qualifyItPayCommand(action.command, agentType))}\n`);
             if (action.requires_human)
                 out("    requires human confirmation\n");
             if (action.reason)
@@ -95,17 +96,17 @@ export function printAgentGuidance(guidance, output) {
         out("recovery:\n");
         for (const action of guidance.recovery) {
             out(`  - ${action.label}\n`);
-            out(`    ${qualifyItPayCommand(action.command, agentType)}\n`);
+            out(`    ${qualifyBackendCommand(qualifyItPayCommand(action.command, agentType))}\n`);
         }
     }
 }
 function qualifyEnvelope(value, agentType) {
     return {
         ...value,
-        next: value.next ? { ...value.next, command: qualifyItPayCommand(value.next.command, agentType) } : null,
+        next: value.next ? { ...value.next, command: qualifyBackendCommand(qualifyItPayCommand(value.next.command, agentType)) } : null,
         recovery: value.recovery.map((action) => ({
             ...action,
-            command: qualifyItPayCommand(action.command, agentType),
+            command: qualifyBackendCommand(qualifyItPayCommand(action.command, agentType)),
         })),
     };
 }
@@ -304,7 +305,7 @@ export function errorRecoveryActions(error) {
         return [
             {
                 id: "retry_after_backend_recovers",
-                label: "Retry after app.itpay.ai is reachable",
+                label: "Retry after the selected official Backend is reachable",
                 command: "itpay readyz",
             },
         ];

package/dist/src/commands/install.js

@@ -7,6 +7,8 @@ export const INSTALL_AGENT_TYPES = [
     "claude-code-desktop",
     "claude-code-cli",
     "workbuddy",
+    "kimi-code",
+    "openclaw",
 ];
 const INSTRUCTIONS = {
     "codex-desktop": "在 Codex Desktop 中始终传这个 Agent Type；付款时把返回的二维码和链接实际展示到当前对话。",
@@ -14,13 +16,12 @@ const INSTRUCTIONS = {
     "claude-code-desktop": "在 Claude Code Desktop 中始终传这个 Agent Type；付款时把返回的二维码和链接实际展示到当前对话。",
     "claude-code-cli": "在 Claude Code CLI 中始终传这个 Agent Type；付款交接只应显示在用户可见终端。",
     workbuddy: "在 WorkBuddy 中始终传这个 Agent Type。运行会持久化 ~/.itpay-v3 的 ItPay Bash 命令前，把 Shell 工具参数 dangerouslyDisableSandbox 设为 true；用户拒绝权限时停止，不要切换 Node、删除 identity 或处理 lock。Checkout 返回 qr_image_url 时，按当次 instruction 调用 present_files 在右侧打开二维码，不要检查本地二维码文件。",
+    "kimi-code": "保持 kimi-code Agent Type，使用标准 CLI 命令和终端付款交接；不要切换到其他平台身份。",
+    openclaw: "保持 openclaw Agent Type；每个展示命令都从当前可信会话上下文显式传 --host，IM 入口同时传 --target。Telegram 使用返回的原生 message action，其他入口展示标准二维码和付款链接。",
 };
 export function runInstall(target, options = {}) {
     if (!target || target === "list") {
-        const agentTypes = INSTALL_AGENT_TYPES.map((agentType) => ({
-            agent_type: agentType,
-            default_host: defaultHostForAgentType(agentType),
-        }));
+        const agentTypes = INSTALL_AGENT_TYPES.map(installDefinition);
         writeCommandEnvelope({
             status: "install_targets",
             result: { agent_types: agentTypes },
@@ -29,7 +30,7 @@ export function runInstall(target, options = {}) {
             recovery: [{ command: "itpay docs show install-and-setup", reason: "查看安装与环境说明" }],
         }, {
             ...options,
-            plainResult: agentTypes.map((item) => `${item.agent_type}: ${item.default_host}`),
+            plainResult: agentTypes.map((item) => `${item.agent_type}: ${item.default_host ?? "explicit --host required"}`),
         });
         return;
     }
@@ -40,19 +41,23 @@ export function runInstall(target, options = {}) {
     writeCommandEnvelope({
         status: "instructions_ready",
         result: {
-            agent_type: normalized,
-            default_host: defaultHostForAgentType(normalized),
+            ...installDefinition(normalized),
             default_api: DEFAULT_BASE_URL,
-            install_command: "npm install -g @itpay/cli",
         },
         instruction: INSTRUCTIONS[normalized],
         next: {
             command: `itpay --agent-type ${normalized} readyz --json`,
-            reason: "验证固定生产 ItPay API 的可用性",
+            reason: "验证当前官方 ItPay API 的可用性",
         },
-        recovery: [{ command: "itpay docs show install-and-setup", reason: "查看固定生产后端和首次使用说明" }],
+        recovery: [{ command: "itpay docs show install-and-setup", reason: "查看官方 Backend 和首次使用说明" }],
     }, options);
 }
 function isInstallAgentType(value) {
     return INSTALL_AGENT_TYPES.includes(value);
 }
+function installDefinition(agentType) {
+    if (agentType === "openclaw") {
+        return { agent_type: agentType, default_host: null, host_required: true, native_hosts: ["telegram"] };
+    }
+    return { agent_type: agentType, default_host: defaultHostForAgentType(agentType) ?? null };
+}

package/dist/src/commands/readyz.js

@@ -2,10 +2,14 @@
 import { writeCommandEnvelope } from "./guidance.js";
 export async function runReadyz(backend, options = {}) {
     const response = await backend.readyz();
+    const backendURL = options.backendURL ?? "https://app.itpay.ai";
+    const environment = options.environment ?? "production";
     writeCommandEnvelope({
         status: response.status,
-        result: { backend: "available", ...(options.agentType ? { agent_type: options.agentType } : {}) },
-        instruction: "ItPay 可用；先完整读取内置 ItPay Skill，再进入当前已支持的 buy 流程。sell 将来也使用同一入口，但当前尚未实现。",
+        result: { backend: "available", backend_url: backendURL, environment, ...(options.agentType ? { agent_type: options.agentType } : {}) },
+        instruction: environment === "development"
+            ? "ItPay dev 可用；后续必须执行返回的完整命令，并继续使用同一个 dev Backend。先完整读取内置 ItPay Skill，再进入当前已支持的 buy 流程。"
+            : "ItPay 可用；先完整读取内置 ItPay Skill，再进入当前已支持的 buy 流程。sell 将来也使用同一入口，但当前尚未实现。",
         next: { command: "itpay skill show itpay --json", reason: "加载完整操作与安全规则" },
         recovery: [],
     }, options);

package/dist/src/commands/services.js

@@ -1,4 +1,5 @@
 import { operationID } from "../state/config.js";
+import { validateContext } from "../state/client_context.js";
 import { dispatchRender } from "../render/index.js";
 import { ensureIdeImageAttach } from "../render/ide.js";
 import { buildCheckoutHandoff, shouldPrepareLocalCheckoutImage } from "./checkout_handoff.js";
@@ -373,6 +374,11 @@ function actionInputError(serviceExecutionID, message, code = "service_action_in
         : "使用当前 safe result 中的合法 action 和 candidate rank；需要人确认时先询问用户。", [{ command: `itpay services next ${serviceExecutionID} --json`, reason: "重新读取同一 Execution 的当前可选动作" }]);
 }
 export async function runServicesCheckout(backend, config, serviceExecutionID, capabilityID, options = {}) {
+    const host = options.host ?? "terminal";
+    const contextError = validateContext(host, options.target);
+    if (contextError) {
+        throw new CommandContractError(contextError.code, contextError.message, "从当前可信会话上下文补齐 Host/target；本次未创建 Checkout。", []);
+    }
     const deliveryContact = {
         ...(options.deliveryContact ?? {}),
         ...(options.email ? { email: options.email } : {}),
@@ -409,12 +415,12 @@ export async function runServicesCheckout(backend, config, serviceExecutionID, c
     const displayToken = checkout.display_token;
     const checkoutURL = tokenizedCheckoutURL(checkout.checkout_url, displayToken, checkout.qr_payload);
     const plan = buildCheckoutQRPlan({
-        host: options.host ?? "terminal",
+        host,
         checkoutID,
         checkoutURL,
         displayToken,
         qrPayload: checkout.qr_payload,
-        ...(checkout.qr_png_url ? { qrPNGURL: checkout.qr_png_url } : {}),
+        ...(checkout.qr_png_url ? { qrPNGURL: absolutePublicURL(config.baseURL, checkout.qr_png_url) } : {}),
         nextAction: checkout.checkout.next_action,
         orderItems: response.cart.items.map((item) => ({
             title: item.title,
@@ -433,9 +439,9 @@ export async function runServicesCheckout(backend, config, serviceExecutionID, c
         checkoutURL,
     });
     const platform = platformKeyForHost(plan.host);
-    if (platform === "telegram" || platform === "feishu" || platform === "lark") {
+    if (!options.jsonOutput && (platform === "telegram" || platform === "feishu" || platform === "lark")) {
         await dispatchRender(plan, {
-            host: options.host ?? "terminal",
+            host,
             ...(options.target ? { target: options.target } : {}),
             ...(options.qrFormat ? { qrFormat: options.qrFormat } : {}),
             ...(options.qrFilePath ? { qrFilePath: options.qrFilePath } : {}),
@@ -452,7 +458,7 @@ export async function runServicesCheckout(backend, config, serviceExecutionID, c
             ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
         });
     }
-    const envelope = buildServicesCheckoutEnvelope(response, checkoutURL, plan, config.baseURL, options.agentType);
+    const envelope = buildServicesCheckoutEnvelope(response, checkoutURL, plan, config.baseURL, options.agentType, options.target);
     const plainResult = [
         `service_execution_id: ${response.binding.service_execution_id}`,
         `checkout_id: ${checkoutID}`,
@@ -933,7 +939,7 @@ function parseValue(value) {
         return Number(value);
     return value;
 }
-function buildServicesCheckoutEnvelope(response, checkoutURL, plan, baseURL, agentType) {
+function buildServicesCheckoutEnvelope(response, checkoutURL, plan, baseURL, agentType, target) {
     const checkout = response.checkout;
     const platform = platformKeyForHost(plan.host);
     const amount = formatMoney(checkout.checkout.amount_minor, checkout.checkout.currency);
@@ -941,7 +947,9 @@ function buildServicesCheckoutEnvelope(response, checkoutURL, plan, baseURL, age
         platform,
         url: checkoutURL,
         amount,
+        plan,
         ...(agentType ? { agentType } : {}),
+        ...(target ? { target } : {}),
         ...(checkout.qr_png_url ? { qrImageURL: absolutePublicURL(baseURL, checkout.qr_png_url) } : {}),
         ...(plan.ideImageAttach?.status === "downloaded" && plan.ideImageAttach.localPath
             ? { localPath: plan.ideImageAttach.localPath }

package/dist/src/main.js

@@ -2,7 +2,7 @@
 // services/backend/internal/httpapi/handlers/*.go. Commands only
 // orchestrate; HTTP and rendering live in src/client and src/render.
 import { Command } from "commander";
-import { CLI_VERSION, loadConfig, cartSessionPath, newBackendClient } from "./state/config.js";
+import { BackendOverrideError, CLI_VERSION, cliDistribution, loadConfig, cartSessionPath, newBackendClient } from "./state/config.js";
 import { DeviceAuthority, DeviceAuthorizationError, DeviceStateError } from "./state/device_authority.js";
 import { CartSession } from "./state/cart_session.js";
 import { defaultHostForAgentType, normalizeHost, validateContext } from "./state/client_context.js";
@@ -29,10 +29,17 @@ program
     .description("V3 ItPay CLI — one entry point for buy workflows and future sell workflows")
     .option("--agent-type <type>", "agent runtime type used for device enrollment and client-specific guidance")
     .version(CLI_VERSION);
-function withHost(value) {
-    const host = normalizeHost(value);
+function withHost(value, agentType, target) {
+    if (!value && agentType?.trim().toLowerCase() === "openclaw") {
+        throw new CommandContractError("host_required", "OpenClaw requires an explicit --host entry", "从当前可信 OpenClaw 会话上下文传入 --host；IM 入口同时传 --target。本次未创建或修改资源。", []);
+    }
+    const host = normalizeHost(value ?? defaultHostForAgentType(agentType));
     if (!host) {
-        throw new Error(`invalid --host "${value ?? ""}". Supported: terminal, codex, claude-code, telegram, discord, whatsapp, feishu, lark, plain-chat`);
+        throw new CommandContractError("invalid_host", `invalid --host "${value ?? ""}". Supported: terminal, codex, claude-code, telegram, discord, whatsapp, feishu, lark, plain-chat`, "传入受支持的展示 Host；本次未创建或修改资源。", []);
+    }
+    const contextError = agentType?.trim().toLowerCase() === "openclaw" ? validateContext(host, target) : undefined;
+    if (contextError) {
+        throw new CommandContractError(contextError.code, contextError.message, "从当前可信会话上下文补齐 --target；本次未创建或修改资源。", []);
     }
     return host;
 }
@@ -83,6 +90,7 @@ function resolveCheckoutPresentationArgs(input) {
 }
 function reportCLIError(error, contract) {
     const commandError = error instanceof CommandContractError ? error : undefined;
+    const backendOverrideError = error instanceof BackendOverrideError ? error : undefined;
     const deviceError = error instanceof DeviceAuthorizationError ? error : undefined;
     const stateError = error instanceof DeviceStateError ? error : undefined;
     const httpRecovery = errorRecoveryActions(error).map((action) => ({
@@ -122,11 +130,11 @@ function reportCLIError(error, contract) {
                 : deviceError
                     ? "Device 身份验证失败；停止重试，不要切换 Agent Type、删除状态或旋转私钥。"
                     : undefined;
-    if (contract || commandError) {
+    if (contract || commandError || backendOverrideError) {
         writeCommandEnvelope({
             status: "error",
             error: {
-                code: incompatible ? "backend_contract_incompatible" : commandError?.code ?? (error instanceof HttpError ? error.code : stateError?.code ?? deviceError?.code ?? contract?.code ?? "command_failed"),
+                code: incompatible ? "backend_contract_incompatible" : backendOverrideError?.code ?? commandError?.code ?? (error instanceof HttpError ? error.code : stateError?.code ?? deviceError?.code ?? contract?.code ?? "command_failed"),
                 message: error instanceof Error ? error.message : String(error),
             },
             ...(requiredCLIVersion ? {
@@ -148,7 +156,7 @@ function reportCLIError(error, contract) {
             } : {}),
             instruction: incompatible
                 ? requiredCLIVersion
-                    ? "当前 CLI 与 Backend 合约不兼容。停止所有 ItPay 业务命令；只执行 recovery.command，将 @itpay/cli 更新到 Backend 指定的精确版本。安装完成后确认 itpay --version 与 result.required_cli_version 完全一致，再重新运行 readyz。不要安装 latest、猜测版本、切换 Agent Type 或删除 Device 身份。"
+                    ? distributionUpgradeInstruction()
                     : "立即向用户报告 error.message 并结束本次任务。Backend 未提供可验证的兼容 CLI 版本；不要运行其他 ItPay 或 npm 命令，不要猜测版本、切换 Agent Type 或删除 Device 身份。"
                 : backendInternal
                     ? "Backend 内部故障；立即停止并向用户报告。不要重试、检查或删除 Device 身份、创建替代 Execution、切换 Backend，或尝试 quote、checkout、cart、buy、pay 等付费路径。"
@@ -164,17 +172,19 @@ function reportCLIError(error, contract) {
                                         ? "Provider 拒绝了本次请求，但未声明这是输入错误；向用户逐字报告 error.message 和 result.quota 并停止。不要修改输入、不要重试、不要创建新 Execution。"
                                         : capabilityInputInvalid
                                             ? "输入未通过本地校验，上游尚未被调用且用户额度未变化。向用户逐字报告 error.message 并停止，不要原样重试或运行其他恢复命令。用户提供修正后的输入后，继续使用当前未结束的 Execution。"
-                                            : commandError?.instruction ?? authorizationInstruction ?? contract?.instruction ?? "检查命令参数后重试。",
+                                            : backendOverrideError
+                                                ? "移除 ITPAY_BACKEND_URL 使用正式环境，或准确设置为 https://dev.itpay.ai。"
+                                                : commandError?.instruction ?? authorizationInstruction ?? contract?.instruction ?? "检查命令参数后重试。",
             next: null,
             recovery: incompatible
                 ? requiredCLIVersion
-                    ? [{ command: `npm install -g @itpay/cli@${requiredCLIVersion}`, reason: "安装 Backend 指定的兼容 CLI 版本" }]
+                    ? [distributionUpgradeAction(requiredCLIVersion)]
                     : []
                 : backendInternal || providerConnectionUnavailable || providerTemporary || providerInputRejected || providerContractMismatch || providerRejected || capabilityInputInvalid
                     ? []
-                    : commandError?.recovery ?? (stateError ? stateRecovery : deviceError ? deviceRecovery : identityRecovery ? httpRecovery : contract?.recovery ?? []),
+                    : backendOverrideError ? [] : commandError?.recovery ?? (stateError ? stateRecovery : deviceError ? deviceRecovery : identityRecovery ? httpRecovery : contract?.recovery ?? []),
         }, {
-            ...(contract?.jsonOutput !== undefined ? { jsonOutput: contract.jsonOutput } : {}),
+            ...(contract?.jsonOutput !== undefined ? { jsonOutput: contract.jsonOutput } : backendOverrideError ? { jsonOutput: process.argv.includes("--json") } : {}),
             output: (text) => { process.stderr.write(text); },
         });
         process.exitCode = 1;
@@ -197,10 +207,29 @@ function docsErrorFallback(jsonOutput) {
     return {
         jsonOutput,
         code: "docs_unavailable",
-        instruction: "内置文档缺失或损坏；重新安装同版本 CLI 后重试。",
-        recovery: [{ command: `npm install -g @itpay/cli@${CLI_VERSION}`, reason: "恢复随包发布的文档" }],
+        instruction: "内置文档缺失或损坏；通过当前分发方式恢复同版本 CLI 后重试。",
+        recovery: [distributionUpgradeAction(CLI_VERSION)],
     };
 }
+function distributionUpgradeAction(version) {
+    switch (cliDistribution()) {
+        case "openclaw-skill-bundle":
+            return { command: "openclaw skills update itpay", reason: `更新包含 ItPay CLI ${version} 的 Skill bundle` };
+        case "kimi-plugin-bundle":
+            return {
+                command: "/plugins install https://github.com/itpay-ai/itpay-plugin-kimi-work",
+                reason: `更新包含 ItPay CLI ${version} 的 Kimi plugin`,
+            };
+        default:
+            return { command: `npm install -g @itpay/cli@${version}`, reason: "安装 Backend 指定的兼容 CLI 版本" };
+    }
+}
+function distributionUpgradeInstruction() {
+    if (cliDistribution() === "npm") {
+        return "当前 CLI 与 Backend 合约不兼容。停止所有 ItPay 业务命令；只执行 recovery.command，将 @itpay/cli 更新到 Backend 指定的精确版本。安装完成后确认 itpay --version 与 result.required_cli_version 完全一致，再重新运行 readyz。不要安装 latest、猜测版本、切换 Agent Type 或删除 Device 身份。";
+    }
+    return "当前平台 bundle 与 Backend 合约不兼容。停止所有 ItPay 业务命令；只执行 recovery.command，更新平台 Skill/plugin 后启动新会话，确认 itpay --version 与 result.required_cli_version 完全一致，再重新运行 readyz。不要运行 npm、猜测版本、切换 Agent Type 或删除 Device 身份。";
+}
 program
     .command("readyz")
     .description("Probe the V3 backend readiness endpoint")
@@ -209,31 +238,34 @@ program
     const config = loadConfig();
     const backend = newBackendClient(config);
     try {
-        await runReadyz(backend, { jsonOutput: Boolean(options.json), ...(config.agentType ? { agentType: config.agentType } : {}) });
+        await runReadyz(backend, {
+            jsonOutput: Boolean(options.json), backendURL: config.baseURL, environment: config.environment,
+            ...(config.agentType ? { agentType: config.agentType } : {}),
+        });
     }
     catch (error) {
         reportCLIError(error, {
             jsonOutput: Boolean(options.json),
             code: "backend_unavailable",
-            instruction: "固定生产后端 https://app.itpay.ai 当前不可用；后端恢复前不要继续下单，也不要切换到其他地址。",
+            instruction: `当前官方 Backend ${config.baseURL} 不可用；恢复前不要继续下单，也不要切换环境。`,
             recovery: [
-                { command: "itpay readyz", reason: "重试固定生产后端的可用性检查" },
+                { command: "itpay readyz", reason: "重试当前官方 Backend 的可用性检查" },
             ],
         });
     }
 });
 // --- device ---------------------------------------------------------------
-const deviceCmd = program.command("device").description("Recover local Device registration state after an operator-confirmed Backend reset");
+const deviceCmd = program.command("device").description("Recover the current official Backend registration after an operator-confirmed reset");
 deviceCmd
     .command("recover")
-    .description("Forget only the app.itpay.ai registration while preserving the local private key")
+    .description("Forget only the current official Backend registration while preserving the local private key")
     .option("--confirm-backend-reset", "confirm that an operator reset the selected Backend registration database")
     .option("--json", "output JSON instead of terminal text")
     .action(async (options) => {
     const config = loadConfig();
     try {
         if (!config.agentType) {
-            throw new CommandContractError("agent_type_required", "agent type is required for app.itpay.ai Device recovery", "如实声明当前 Agent Type；恢复后必须用同一类型重新登记。", [{ command: "itpay install --json", reason: "选择当前真实 Agent Type" }]);
+            throw new CommandContractError("agent_type_required", `agent type is required for ${config.baseURL} Device recovery`, "如实声明当前 Agent Type；恢复后必须用同一类型重新登记。", [{ command: "itpay install --json", reason: "选择当前真实 Agent Type" }]);
         }
         if (!options.confirmBackendReset) {
             throw new CommandContractError("backend_reset_confirmation_required", "--confirm-backend-reset is required", "仅在运营已确认当前 Backend 的 Device 登记数据库被重建或清空后执行；普通 session 失效或 revoked 不得使用。", [{ command: "itpay docs show identity-and-sessions --json", reason: "检查适用边界" }]);
@@ -292,8 +324,8 @@ skillCmd
         reportCLIError(error, {
             jsonOutput: Boolean(options.json),
             code: "skill_unavailable",
-            instruction: "内置 Skill 缺失或损坏；重新安装同版本 CLI 后重试。",
-            recovery: [{ command: `npm install -g @itpay/cli@${CLI_VERSION}`, reason: "恢复随包发布的 Skill" }],
+            instruction: "内置 Skill 缺失或损坏；通过当前分发方式恢复同版本 CLI 后重试。",
+            recovery: [distributionUpgradeAction(CLI_VERSION)],
         });
     }
 });
@@ -450,7 +482,7 @@ cart
             runCartAdd(session, { ...addOptions, jsonOutput });
         }
         else {
-            const host = withHost(options.host ?? defaultHostForAgentType(config.agentType));
+            const host = withHost(options.host, config.agentType, options.target);
             const contextError = validateContext(host, options.target);
             if (contextError) {
                 throw new CommandContractError(contextError.code, contextError.message, "补齐当前客户端所需的 Host/target；本次未创建或修改 Cart。", [{ command: "itpay cart add --help", reason: "查看客户端参数" }]);
@@ -686,7 +718,7 @@ program
         }
         const quantity = positiveInteger(options.quantity, "--quantity");
         const timeout = positiveInteger(options.timeout, "--timeout");
-        const host = withHost(options.host ?? defaultHostForAgentType(config.agentType));
+        const host = withHost(options.host, config.agentType, options.target);
         const contact = {};
         if (options.contactEmail)
             contact.email = options.contactEmail;
@@ -750,11 +782,11 @@ program
     .option("--json", "output compact JSON")
     .action(async (options) => {
     const config = loadConfig();
-    const host = withHost(options.host ?? defaultHostForAgentType(config.agentType));
     const session = CartSession.loadFromFile(cartSessionPath(), config.checkoutCurrency);
     const snap = session.show();
     const backend = newBackendClient(config);
     try {
+        const host = withHost(options.host, config.agentType, options.target);
         const { checkoutID, displayToken } = resolveCheckoutPresentationArgs({
             ...(options.id ? { requestedCheckoutID: options.id } : {}),
             ...(options.token ? { requestedDisplayToken: options.token } : {}),
@@ -765,6 +797,7 @@ program
             checkoutID,
             displayToken,
             host,
+            ...(options.target ? { target: options.target } : {}),
             ...(config.agentType ? { agentType: config.agentType } : {}),
             baseURL: config.baseURL,
             jsonOutput: Boolean(options.json),
@@ -811,7 +844,7 @@ program
         if (!displayToken) {
             throw new CommandContractError("checkout_token_required", "display token is required for this checkout", "提供同一 Checkout 的 display token；不要拼接其他 Checkout 的 token。", [{ command: "itpay next --json", reason: "恢复本机保存的同一 Checkout" }]);
         }
-        const host = withHost(options.host ?? defaultHostForAgentType(config.agentType));
+        const host = withHost(options.host, config.agentType, options.target);
         const contextError = validateContext(host, options.target);
         if (contextError) {
             throw new CommandContractError(contextError.code, contextError.message, "为当前 Host 提供有效 target；本次未创建 Payment Intent。", [
@@ -1018,7 +1051,7 @@ services
     const backend = newBackendClient(config);
     try {
         await runServicesStart(backend, serviceID, {
-            host: withHost(options.host ?? defaultHostForAgentType(config.agentType)),
+            host: withHost(options.host, config.agentType, options.target),
             ...(options.target ? { target: options.target } : {}),
             jsonOutput: Boolean(options.json),
         });
@@ -1144,7 +1177,7 @@ services
             ...(options.email ? { email: options.email } : {}),
             lockedInput: parseKeyValueList(options.input),
             resume: Boolean(options.resume),
-            host: withHost(options.host ?? defaultHostForAgentType(config.agentType)),
+            host: withHost(options.host, config.agentType, options.target),
             ...(config.agentType ? { agentType: config.agentType } : {}),
             ...(options.target ? { target: options.target } : {}),
             ...(options.qrFormat ? { qrFormat: options.qrFormat } : {}),