@qingtui/openclaw-plugin 0.0.0-stage → 1.1.0

package/dist/src/inbound.js

@@ -0,0 +1,301 @@
+/**
+ * nudge 入站消息处理。
+ *
+ * 入站通道不是 webhook：插件启动时由 src/service.ts 注册的后台 service
+ * （qingtui-inbound）通过轻推 Socket SDK 建立长连接，nudge 服务器把消息
+ * 推送过来；src/event.ts 负责归一化与去重，本模块负责准入、路由与派发。
+ *
+ * 【新手须知】术语：
+ *   ingress  OpenClaw 的入站访问控制判定（allowlist 策略）
+ *   route    决定由哪个 agent、哪个会话 sessionKey 处理本条消息
+ *
+ * 完整入站流水线见 handleNudgeInboundMessage 的 doc。
+ * 调用方：src/service.ts 的后台 service（每条 socket 推送调一次）。
+ */
+import { defineStableChannelIngressIdentity, resolveChannelMessageIngress, } from "openclaw/plugin-sdk/channel-ingress-runtime";
+import { isControlCommandMessage, shouldComputeCommandAuthorized, } from "openclaw/plugin-sdk/command-detection";
+import { getAgentScopedMediaLocalRoots } from "openclaw/plugin-sdk/media-local-roots";
+import { resolveOutboundMediaUrls, } from "openclaw/plugin-sdk/reply-payload";
+import { encodeNudgeTarget, getDynamicAllowFrom, nudgeChatApi, nudgeStreamApi, } from "./client.js";
+import { isNudgeStreamingEnabled, NUDGE_CHANNEL_ID, resolveAccount, } from "./config.js";
+import { createEventDeduper } from "./event.js";
+import { NudgeReplyStream } from "./stream.js";
+export { normalizeNudgeEvent } from "./event.js";
+/** 重推/重连可能重复投递同一 event_id；按账号维度去重 */
+const deduper = createEventDeduper();
+/**
+ * 轻推入站的身份描述：以 open_id / channel_id 为稳定主键。
+ * 不支持通配：白名单只来自平台同步的可见范围，任何条目都不能放开全部发送者。
+ */
+const nudgeIngressIdentity = defineStableChannelIngressIdentity({
+    kind: "stable-id",
+    isWildcardEntry: () => false,
+});
+/**
+ * 处理一条已归一化的 nudge 入站消息。
+ * 由 src/service.ts 的 WebSocket service 在收到推送时调用。
+ *
+ * 完整入站链路（对齐内置渠道 nextcloud-talk / telegram）：
+ *  1. 访问控制：resolveChannelMessageIngress（allowlist 策略 + 动态白名单）
+ *     - 拒绝：静默丢弃
+ *  2. 路由：resolveAgentRoute 决定 agentId + sessionKey
+ *  3. 上下文：buildChannelInboundEventContext 组装 prompt 上下文
+ *  4. 投递：dispatchReply 跑 ingest -> resolve -> record -> dispatch，
+ *     回复经 delivery 适配器 -> nudgeChatApi.sendMessage 发回 nudge
+ */
+export async function handleNudgeInboundMessage(params) {
+    const { event, accountId, runtime, logger } = params;
+    const tag = accountId ? `[${accountId}]` : "";
+    if (deduper.isDuplicate(accountId ?? "default", event.id)) {
+        logger?.info(`openclaw-nudge${tag}: 忽略重复事件 ${event.id}`);
+        return;
+    }
+    if (!runtime) {
+        // service 启动晚于 register，正常不会发生；保守处理
+        logger?.warn(`openclaw-nudge${tag}: runtime 未就绪，丢弃入站消息`);
+        return;
+    }
+    // runtime.config.current() 返回 DeepReadonly<OpenClawConfig>，
+    // 下游 API 签名要求 OpenClawConfig，只读保护在插件层面无影响，断言去除。
+    const cfg = runtime.config.current();
+    let account;
+    try {
+        account = resolveAccount(cfg, accountId);
+    }
+    catch (err) {
+        logger?.error(`openclaw-nudge${tag}: 账号解析失败: ${String(err)}`);
+        return;
+    }
+    // -----------------------------------------------------------------------
+    // 1. 访问控制：resolveChannelMessageIngress
+    // -----------------------------------------------------------------------
+    // /new /reset 等文本控制命令由 openclaw 回复管线执行，但只在入站上下文
+    // CommandAuthorized=true 时生效：疑似命令消息要求 ingress 附带命令门控，
+    // 命令 owner 白名单缺省取 effective DM 白名单（即动态白名单，与发送者
+    // 准入同源），白名单内的用户即可执行命令（对齐 clickclack 官方接线）。
+    const commandCheckRequested = shouldComputeCommandAuthorized(event.text, cfg);
+    // biome-ignore lint/suspicious/noImplicitAnyLet: openclaw 没导出ResolvedChannelMessageIngress
+    let ingress;
+    try {
+        // 群聊白名单存的是 channel_id（平台同步的"应用可见范围"里群聊与用户
+        // open_id 合并在同一数组），因此群聊的准入主体用 channel_id 匹配；
+        // 单聊仍用发送者 id。
+        const ingressSubject = event.chatType === "group" ? event.chatId : event.from;
+        const dynamicAllowList = [...getDynamicAllowFrom(account.accountId)];
+        ingress = await resolveChannelMessageIngress({
+            channelId: NUDGE_CHANNEL_ID,
+            accountId: account.accountId,
+            identity: nudgeIngressIdentity,
+            subject: { stableId: ingressSubject },
+            conversation: { kind: event.chatType, id: event.chatId },
+            event: {
+                kind: "message",
+                authMode: "inbound",
+                mayPair: false, // allowlist 策略固定不触发 pairing
+            },
+            policy: {
+                dmPolicy: "allowlist",
+                groupPolicy: "allowlist",
+            },
+            allowFrom: dynamicAllowList,
+            groupAllowFrom: dynamicAllowList,
+            command: commandCheckRequested
+                ? {
+                    // 只算授权不拦截：未授权的控制命令按普通文本继续进 agent
+                    allowTextCommands: false,
+                    hasControlCommand: isControlCommandMessage(event.text, cfg),
+                }
+                : undefined,
+        });
+    }
+    catch (err) {
+        logger?.error(`openclaw-nudge${tag}: 访问控制解析失败: ${String(err)}`);
+        return;
+    }
+    // 1a. 拒绝：静默丢弃
+    if (!ingress.senderAccess.allowed) {
+        logger?.info(`openclaw-nudge${tag}: 入站消息被拒绝` +
+            ` (chat=${event.chatType}, subject=${event.chatType === "group" ? event.chatId : event.from},` +
+            ` reason=${ingress.senderAccess.reasonCode})`);
+        return;
+    }
+    // -----------------------------------------------------------------------
+    // 2. 路由：决定 agentId + sessionKey
+    // -----------------------------------------------------------------------
+    const peerKind = event.chatType === "group" ? "group" : "direct";
+    // 路由 peer ID：群聊把 channel_id 与发送者编在一起，确保同一群里不同
+    // 用户各自独立会话（session key = agent:main:qingtui:group:<channel>:<sender>）；
+    // 单聊直接用发送者 id。
+    const routePeerId = event.chatType === "group" ? `${event.chatId}:${event.from}` : event.from;
+    const route = runtime.channel.routing.resolveAgentRoute({
+        cfg,
+        channel: NUDGE_CHANNEL_ID,
+        accountId: account.accountId,
+        peer: { kind: peerKind, id: routePeerId },
+        // 宿主缺省 dmScope 为 "main"，会把所有用户的单聊并入同一会话；
+        // 未显式配置 session.dmScope 时按账号+发送者隔离。
+        dmScope: cfg.session?.dmScope ?? "per-account-channel-peer",
+    });
+    // -----------------------------------------------------------------------
+    // 3. 组装入站上下文（prompt 字段）
+    // -----------------------------------------------------------------------
+    // 出站目标始终用群 id（encodeNudgeTarget 编码 channel_id），不受路由
+    // peer ID 影响：回复发回群里，不按用户拆分。
+    const toTarget = encodeNudgeTarget(event.chatType, event.chatId);
+    const ctxPayload = runtime.channel.inbound.buildContext({
+        channel: NUDGE_CHANNEL_ID,
+        accountId: account.accountId,
+        messageId: event.id,
+        timestamp: event.timestamp,
+        from: event.from,
+        sender: { id: event.from },
+        conversation: { kind: event.chatType, id: event.chatId },
+        route: {
+            agentId: route.agentId,
+            accountId: account.accountId,
+            routeSessionKey: route.sessionKey,
+        },
+        reply: { to: toTarget },
+        message: { rawBody: event.text },
+        access: {
+            // DM/群聊准入决定已由上方 resolveChannelMessageIngress 消化（被拒
+            // 消息提前丢弃），2026.8.1 起 access 只收命令授权等剩余字段
+            // CommandAuthorized 只对命令型消息生效；未请求命令门控时回退发送者
+            // 准入结果（走到这里必为 true），与 clickclack 语义一致
+            commands: {
+                authorized: ingress.commandAccess.requested
+                    ? ingress.commandAccess.authorized
+                    : ingress.senderAccess.allowed,
+            },
+        },
+    });
+    // storePath：会话持久化目录（按 agent + 配置 store 路径定位）
+    const storePath = runtime.channel.session.resolveStorePath(cfg.session?.store, {
+        agentId: route.agentId,
+    });
+    // 回复附件的本地读取根目录：入站 deliver 不经渠道 outbound.sendMedia，
+    // 宿主不会注入 mediaAccess，按路由 agent 取宿主授权根目录（对齐内置
+    // telegram 入站接线）；远程 URL 仍受宿主加载器的 SSRF 策略约束。
+    const mediaLocalRoots = getAgentScopedMediaLocalRoots(cfg, route.agentId);
+    // -----------------------------------------------------------------------
+    // 4. 投递：record + dispatch（agent 回复在这里发回 nudge）
+    // -----------------------------------------------------------------------
+    logger?.info(`openclaw-nudge${tag}: 派发入站消息` +
+        ` (from=${event.from}, agent=${route.agentId}, session=${route.sessionKey})`);
+    // 流式回复：仅单聊启用（群聊消息密度高、多用户并发，流式占位协议
+    // 容易冲突，直接走普通文本更稳）；渠道未关闭 streaming 且事件携带
+    // account_id（轻推流式占位接口的 launchAccountId；launchMsgId 归一化
+    // 时已保证存在）时启用。任一条件不满足时 stream 为 null，走普通文本。
+    const stream = isNudgeStreamingEnabled(cfg) &&
+        event.chatType === "direct" &&
+        event.senderAccountId
+        ? new NudgeReplyStream({
+            ctx: {
+                accountId: account.accountId,
+                to: toTarget,
+                launchMsgId: event.msgId,
+                launchAccountId: event.senderAccountId,
+            },
+            api: nudgeStreamApi,
+            logger,
+        })
+        : null;
+    try {
+        await runtime.channel.inbound.dispatchReply({
+            cfg,
+            channel: NUDGE_CHANNEL_ID,
+            accountId: account.accountId,
+            agentId: route.agentId,
+            routeSessionKey: route.sessionKey,
+            storePath,
+            ctxPayload,
+            recordInboundSession: runtime.channel.session.recordInboundSession,
+            dispatchReplyWithBufferedBlockDispatcher: runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher,
+            delivery: {
+                deliver: async (payload, info) => {
+                    // deliver 被 dispatchReply 以 fire-and-forget 方式调用，
+                    // 内部抛出的错误会被静默吞掉；try/catch + logger.error
+                    // 保证错误能进入 gateway 日志。
+                    try {
+                        const text = payload.text ?? "";
+                        const mediaUrls = resolveOutboundMediaUrls(payload);
+                        if (!text && mediaUrls.length === 0)
+                            return;
+                        // final 且已开流：补发剩余增量并 status=2 收尾，不再另发
+                        // 普通文本；未开流/流式失败时回退普通文本。其他 kind
+                        // （tool 等）仍按独立消息发送。
+                        let textHandled = !text;
+                        if (text && stream && (!info?.kind || info.kind === "final")) {
+                            textHandled = await stream.finish(text);
+                        }
+                        // 附件逐个上传发送（不带文字，文字统一在后面单独发）。
+                        // 单个附件失败不影响其余附件和文字，全部发完后再抛错记日志。
+                        let mediaError;
+                        for (const mediaUrl of mediaUrls) {
+                            try {
+                                await nudgeChatApi.sendFile({
+                                    accountId: account.accountId,
+                                    to: toTarget,
+                                    mediaUrl,
+                                    mediaAccess: { localRoots: mediaLocalRoots },
+                                });
+                            }
+                            catch (err) {
+                                mediaError ??= err;
+                                logger?.error(`openclaw-nudge${tag}: 附件发送失败: ${String(err?.message ?? err)}`);
+                            }
+                        }
+                        if (!textHandled) {
+                            // 群聊回复时引用入站提问消息（event.msgId），
+                            // 单聊无引用（sendMessage 内部已按 sendType 判断）。
+                            await nudgeChatApi.sendMessage({
+                                accountId: account.accountId,
+                                to: toTarget,
+                                text,
+                                replyToId: event.chatType === "group" ? event.msgId : undefined,
+                            });
+                        }
+                        if (mediaError)
+                            throw mediaError;
+                    }
+                    catch (deliverErr) {
+                        logger?.error(`openclaw-nudge${tag}: delivery.deliver 失败` +
+                            ` (kind=${info?.kind ?? "?"}): ${String(deliverErr?.message ?? deliverErr)}`);
+                        throw deliverErr;
+                    }
+                },
+                // biome-ignore lint/suspicious/noExplicitAny: onError 签名来自 openclaw 内部
+                onError: (err, info) => {
+                    logger?.error(`openclaw-nudge${tag}: delivery.onError` +
+                        ` (kind=${info?.kind ?? "?"}): ${String(err?.message ?? err)}`);
+                },
+            },
+            replyPipeline: {},
+            replyOptions: {
+                // 块流式会把回复拆成多条独立 block 消息：单聊与流式占位冲突，
+                // 群聊要求一次发完整内容，因此始终关闭（对齐 qqbot 官方流式接线）
+                disableBlockStreaming: true,
+                ...(stream
+                    ? {
+                        onPartialReply: async (payload) => {
+                            await stream.update(payload.text ?? "");
+                        },
+                        // 推理模型的正文要等回合结束才下发（宿主限制），先流式展示
+                        // 思考过程；非 /reasoning stream 会话也需显式开启推理流
+                        streamReasoningInNonStreamModes: true,
+                        onReasoningStream: async (payload) => {
+                            await stream.updateReasoning(payload.text ?? "");
+                        },
+                    }
+                    : {}),
+            },
+        });
+        // 无 final 投递（如 NO_REPLY）时占位不能悬空：把节流残留的增量
+        // 补发完并静默收尾（未开流时是空操作）
+        await stream?.finish("");
+    }
+    catch (err) {
+        logger?.error(`openclaw-nudge${tag}: 入站回复派发失败: ${String(err)}`);
+        await stream?.abort();
+    }
+}

package/dist/src/logger.js

@@ -0,0 +1 @@
+export {};

package/dist/src/service.js

@@ -0,0 +1,115 @@
+import { connectNudgeSocket, disconnectNudgeSocket, refreshDynamicAllowFrom, resetDynamicAllowFrom, } from "./client.js";
+import { isNudgeChannelEnabled, listConfiguredNudgeAccounts, resolveNudgeOpenUrl, resolveNudgeServerUrl, } from "./config.js";
+import { handleNudgeInboundMessage, normalizeNudgeEvent } from "./inbound.js";
+const ALLOW_FROM_REFRESH_INTERVAL_MS = 5 * 60 * 1000;
+/**
+ * 组装入站 service。getRuntime 取入口保存的 PluginRuntime 句柄
+ * （入站派发要用；setRuntime 先于 service start 执行）。
+ * 调用方：index.ts registerFull（仅 full 模式）。
+ */
+export function createNudgeInboundService(getRuntime) {
+    // 白名单定时刷新句柄归属本 service 实例；stop 时清理
+    let allowFromTimer = null;
+    return {
+        id: "qingtui-inbound",
+        start: async (ctx) => {
+            if (!isNudgeChannelEnabled(ctx.config)) {
+                ctx.logger.info("qingtui: 渠道已禁用（enabled:false），跳过连接");
+                return;
+            }
+            const accounts = listConfiguredNudgeAccounts(ctx.config);
+            if (accounts.length === 0) {
+                ctx.logger.info("qingtui: 未配置 appid/appsecret，跳过连接");
+                return;
+            }
+            const serverUrl = resolveNudgeServerUrl(ctx.config);
+            const openUrl = resolveNudgeOpenUrl(ctx.config);
+            ctx.logger.info(`qingtui: 轻推服务地址 ${serverUrl}（REST ${openUrl}），账号 ${accounts.length} 个`);
+            // 白名单同步函数与定时器必须先于 connect 定义 —— onAuthenticated/
+            // onReconnected 闭包引用它们，且 SDK 在首次 connect 失败后的自动
+            // 重连成功时也会触发这两个回调（后置声明会落入 TDZ）。
+            // 首次同步成功前白名单为空 —— fail-closed，全部拒绝。
+            const syncAllowFrom = (accountId) => refreshDynamicAllowFrom(accountId)
+                .then((count) => {
+                if (count !== null)
+                    ctx.logger.info(`qingtui[${accountId}]: 动态白名单已同步（${count} 条）`);
+            })
+                .catch((error) => {
+                ctx.logger.warn(`qingtui[${accountId}]: 动态白名单同步失败（保留旧缓存）: ${String(error)}`);
+            });
+            const syncAndScheduleAllowFrom = (accountId) => {
+                void syncAllowFrom(accountId);
+                if (!allowFromTimer)
+                    allowFromTimer = setInterval(() => {
+                        for (const account of accounts)
+                            void syncAllowFrom(account.accountId);
+                    }, ALLOW_FROM_REFRESH_INTERVAL_MS);
+            };
+            // 多机器人：为每个已配置账号建一条独立连接（一个失败不影响其余）
+            for (const account of accounts) {
+                const { accountId } = account;
+                try {
+                    await connectNudgeSocket(accountId, {
+                        appid: account.appid,
+                        appsecret: account.appsecret,
+                        serverUrl,
+                        openUrl,
+                    }, {
+                        onMessage: (message) => {
+                            // 解析失败或非消息事件：忽略（SDK 已 autoAck）
+                            const event = normalizeNudgeEvent(message);
+                            if (!event) {
+                                ctx.logger.debug?.(`qingtui[${accountId}]: 忽略非消息事件或残缺负载`);
+                                return;
+                            }
+                            // 只记录元数据，不落消息正文
+                            ctx.logger.debug?.(`qingtui[${accountId}]: 收到消息 id=${event.id} chat=${event.chatType} len=${event.text.length}`);
+                            void handleNudgeInboundMessage({
+                                event,
+                                accountId,
+                                runtime: getRuntime(),
+                                logger: ctx.logger,
+                            }).catch((error) => {
+                                ctx.logger.error(`qingtui[${accountId}]: 入站消息处理失败: ${String(error)}`);
+                            });
+                        },
+                        onAuthenticated: () => {
+                            ctx.logger.info(`qingtui[${accountId}]: socket 认证成功`);
+                            syncAndScheduleAllowFrom(accountId);
+                        },
+                        onDisconnected: (reason) => {
+                            ctx.logger.warn(`qingtui[${accountId}]: socket 断开（${reason}），SDK 将自动重连`);
+                        },
+                        onReconnected: () => {
+                            ctx.logger.info(`qingtui[${accountId}]: socket 重连成功`);
+                            // 重连后白名单缓存可能已过期，立即刷新并确保定时器在
+                            syncAndScheduleAllowFrom(accountId);
+                        },
+                        onError: (error) => {
+                            ctx.logger.error(`qingtui[${accountId}]: socket 错误: ${error.message}`);
+                        },
+                        onHeartbeatTimeout: () => {
+                            ctx.logger.warn(`qingtui[${accountId}]: socket 心跳超时`);
+                        },
+                    });
+                    ctx.logger.info(`qingtui[${accountId}]: 已连接轻推消息代理`);
+                }
+                catch (error) {
+                    // 首次连接失败：SDK 内部已安排自动重连（指数退避），
+                    // 这里只记录日志，不让 gateway service 启动失败
+                    ctx.logger.error(`qingtui[${accountId}]: 首次连接失败（SDK 将自动重试）: ${String(error)}`);
+                }
+            }
+        },
+        stop: async () => {
+            // 主动断开全部账号连接并停止重连
+            disconnectNudgeSocket();
+            // 停止白名单刷新并清缓存，回到 fail-closed 初始态
+            if (allowFromTimer) {
+                clearInterval(allowFromTimer);
+                allowFromTimer = null;
+            }
+            resetDynamicAllowFrom();
+        },
+    };
+}

package/dist/src/setup-wizard.js

@@ -0,0 +1,94 @@
+/**
+ * 交互式配置向导：用户跑 `openclaw channels add` 时终端里的提问流程。
+ *
+ * 【新手须知】声明式向导 = 用数据描述"问什么、怎么校验、怎么写盘"，
+ * 提问渲染由 OpenClaw CLI 完成。本渠道流程固定为：选账号（可 Add a new
+ * account 新建机器人）-> 录入 appid -> 录入 appsecret（掩码）-> 录入轻推
+ * 服务地址（渠道级，所有账号共用）-> 回渠道列表（可继续添加）->
+ * Finished 后 CLI 才统一写盘（中途取消全部丢弃）。
+ * 没有 DM 策略提问：本渠道私聊策略固定为 allowlist（见 src/channel.ts
+ * security 段），白名单只能来自轻推服务器同步，无配置键。
+ */
+import { createStandardChannelSetupStatus, setSetupChannelEnabled, } from "openclaw/plugin-sdk/setup";
+import { DEFAULT_NUDGE_SERVER_URL, isNudgeAccountConfigured, isNudgeChannelConfigured, NUDGE_CHANNEL_ID, normalizeNudgeUrl, patchNudgeAccountConfig, patchNudgeServerUrl, readConfiguredNudgeServerUrl, readNudgeAccountConfig, } from "./config.js";
+// 多账号：resolveShouldPromptAccountIds 恒 true，向导在凭证录入前弹账号
+// 选择（含 "Add a new account"），每轮配置可继续添加新机器人。
+export const nudgeSetupWizard = {
+    channel: NUDGE_CHANNEL_ID,
+    // 支持同时接入多个机器人：弹账号选择（含 Add a new account）
+    resolveShouldPromptAccountIds: () => true,
+    status: createStandardChannelSetupStatus({
+        channelLabel: "Qingtui（轻推）",
+        configuredLabel: "已配置",
+        unconfiguredLabel: "未配置（需要机器人ID和Secret）",
+        configuredHint: "appid/appsecret 已配置",
+        unconfiguredHint: "需要 appid + appsecret",
+        configuredScore: 1,
+        unconfiguredScore: 0,
+        resolveConfigured: ({ cfg, accountId }) => accountId
+            ? isNudgeAccountConfigured(cfg, accountId)
+            : isNudgeChannelConfigured(cfg),
+    }),
+    // appsecret 走 textInputs 而非 credentials：credential 步骤会先弹
+    // plaintext / 外部 secret provider 模式选择，声明式向导不支持按渠道关闭。
+    // textInput 的 sensitive:true 提供掩码录入，且不回显已存值。
+    credentials: [],
+    textInputs: [
+        {
+            inputKey: "userId",
+            message: "轻推机器人 ID (appid)",
+            placeholder: "轻推平台分配的机器人ID",
+            currentValue: ({ cfg, accountId }) => {
+                const appid = readNudgeAccountConfig(cfg, accountId)?.appid;
+                return typeof appid === "string" && appid ? appid : undefined;
+            },
+            validate: ({ value }) => (value ? undefined : "必填"),
+            applySet: async ({ cfg, accountId, value }) => patchNudgeAccountConfig({ cfg, accountId, patch: { appid: value } }),
+        },
+        {
+            inputKey: "secret",
+            message: "输入轻推机器人密钥 (appsecret)",
+            placeholder: "轻推平台分配的机器人密钥",
+            // 掩码录入；重跑时只问是否保留，不展示已存密钥
+            sensitive: true,
+            keepPrompt: "已配置机器人密钥，是否保留？",
+            currentValue: ({ cfg, accountId }) => {
+                const appsecret = readNudgeAccountConfig(cfg, accountId)?.appsecret;
+                return typeof appsecret === "string" && appsecret
+                    ? appsecret
+                    : undefined;
+            },
+            validate: ({ value }) => (value ? undefined : "必填"),
+            applySet: async ({ cfg, accountId, value }) => patchNudgeAccountConfig({
+                cfg,
+                accountId,
+                patch: { appsecret: value },
+            }),
+        },
+        {
+            inputKey: "serverUrl",
+            message: "轻推服务地址",
+            placeholder: DEFAULT_NUDGE_SERVER_URL,
+            helpTitle: "轻推服务地址",
+            helpLines: [
+                `生产环境：${DEFAULT_NUDGE_SERVER_URL}`,
+                "QA 环境：https://qaqtopen.qingtui.com",
+                "渠道级配置，所有机器人账号共用；REST 地址未单独配置 openUrl 时同此地址",
+            ],
+            keepPrompt: (value) => `轻推服务地址为 ${value}，是否保留？`,
+            currentValue: ({ cfg }) => readConfiguredNudgeServerUrl(cfg),
+            initialValue: () => DEFAULT_NUDGE_SERVER_URL,
+            validate: ({ value }) => normalizeNudgeUrl(value) ? undefined : "请输入 http(s) 开头的完整地址",
+            normalizeValue: ({ value }) => normalizeNudgeUrl(value) ?? value,
+            applySet: async ({ cfg, value }) => patchNudgeServerUrl(cfg, value),
+        },
+    ],
+    completionNote: {
+        title: "轻推机器人凭证已录入",
+        lines: [
+            "配置尚未保存：回到渠道列表选择 Finished，看到 Channels updated. 才算保存",
+            "重启 gateway 生效：openclaw gateway restart",
+        ],
+    },
+    disable: (cfg) => setSetupChannelEnabled(cfg, NUDGE_CHANNEL_ID, false),
+};