fix(approval): harden native approval handling

[zhumin-zizhu]

背景

GAP-01 是 docs/features-gap.html 列出的 P0 缺口 #1:DingTalk channel 接入 OpenClaw 原生审批能力(exec approval + plugin approval)。Spec v3.12 + plan v6(26 task)与 21 commit 的实现都在本 PR 内,review 反馈也已合入。

范围

• 接入上游 ChannelApprovalCapability 与 native runtime 4 sub-adapter(availability / presentation / transport / observe;interactions 留待 v2)。
• AI Card v3 模板:把 3 个 approval 按钮挂到原 agent reply card 上(show_approve_btns / hasAction / approveId 三个变量 PUT)。
• Markdown fallback:无 active card 时发独立 /approve <id> <decision> 命令模板。
• 按钮回调与 /approve 命令两条入口都收敛到 approval-resolver,再调上游 resolveApprovalOverGateway。
• v1 仅 origin-only 投递,approver DM 双投递推迟到 v2。

关键改动

• 新增 src/approval/ 域:config / schema / parser / target-resolver / resolver / runtime / capability / card-locator / card-patcher / card-state / callback-handler / command-intercept / markdown-render(13 个模块,~900 LOC)。
• card-run-registry 加 isActiveCardRun / resolveActiveCardRunBySession / markCardRunPendingApproval / clearCardRunPendingApproval,approval 复用现有 card 状态,不引入独立 store。
• card-callback-service.analyzeCardCallback 输出 cardPrivateData.{actionIds, params},让 approval handler 解出 approveId / action。
• card-service 在 createAICard / commit / finalizeStopped 三处都写入 APPROVAL_CARD_INITIAL,模板初始化对齐。
• channel.ts 挂 approvalCapability(thin layer 守住);channel-gateway 在 TOPIC_CARD listener 接入 approval 分支;inbound-handler 在 session lock 前早期拦截 /approve 命令(绕过 agent session lock)。
• 配置层:channels.dingtalk.execApprovals.{ enabled, approvers },空时回退 commands.ownerAllowFrom。
• SDK baseline bump:openclaw peerDep + lockfile + manifest + tsconfig;message-tool capability 从 cards 改为 presentation(对齐上游 deprecation)。

上游 openclaw 依赖(>=2026.5.7)

本 PR 用到的三个 SDK API 各自引入版本:

API	引入版本
"presentation" channel-message capability	2026.4.21
createChannelNativeOriginTargetResolver({ normalizeTarget })	2026.4.27
PluginApprovalRequestPayload.allowedDecisions	2026.5.7

取 max = 2026.5.7。peerDep 抬到 >=2026.5.7,并用 pnpm.overrides 把实装也 pin 在这个版本(避免 fresh install 漂到更新的 5.7)。

CI Node 22

ci-tests.yml 从 node-version: 20 升到 22。openclaw@2026.5.7 拉的 undici@8.x 自报 engines.node: ">=22.19.0" 并使用 webidl.util.markAsUncloneable(Node 21.3+ API),Node 20 上会报 TypeError。22 与上游 openclaw 自身的 engines.node: ">=22.16.0" 对齐,且 setup-node@v4 在 22 下当前拿到 22.20+,满足 undici 8.x。npm-publish.yml / clawhub-publish.yml 早已 Node 24,无需动;docs-vercel.yml 仍在 20,build 路径不触发 undici,本 PR 不顺带改。

Review 反馈修复(已合入)

• 安全:approval-resolver.deriveGatewayParams 把鉴权门挪到 plugin: 前缀短路之前,防止未授权用户通过 /approve plugin:<id> 绕过 channel approver 名单(004ea4f)。
• 并发:findActiveAgentCard 拒绝有不同 pendingApprovalId 的 active card,第二个 approval 自动走 markdown 路径;dedupeKey 同时加 ${request.id}(004ea4f)。
• 可靠性:callback handler 先做 resolveApproval 再 best-effort patch 卡片,即使 token / 卡片 patch 失败也不阻断上游 resolve;空 approvalId 时仅在 params.action 明确是审批动作才处理,避免误吞普通按钮(8c77f05)。
• 重试语义:callback 和 /approve 在 gateway-error 都保留 pending + 私聊"稍后重试"提示,不再激进 expire 卡片(8c77f05)。
• 错误分类:shouldFallbackToMarkdown 单一 helper 替换冗余双分支(004ea4f)。
• 文案:按钮决策标签统一为 允许一次 / 总是允许 / 拒绝,与 user docs 对齐(004ea4f)。
• 死代码注释:isPluginAuthorizedSender 共享 exec 名单这一 v2 占位加显式注释(004ea4f)。
• 集成测试覆盖:补完 plan Task 21 的 12 场景 integration test(tests/integration/approval-end-to-end.test.ts),覆盖 multi-approver 竞争 / self-approval DM / 非 approver 点击 / 上游 expired event / card patch 明确失败降级 markdown / 模糊失败 return null / /approve 命令绕过 session lock / 未配 approvers / 非 dingtalk 触发 / 重启后旧按钮 not-found / exec & plugin invalid-decision —— 共 12 个 spec §9.3 列出的关键场景(3b1b023)。

Deferred / 后续

• approver DM 双投递 留 v2,本 PR 仅 origin-only。
• 重启后主动 rebind pending approval 留 v2,用户点旧按钮显式降级提示。

文档

• docs/user/features/exec-approval.md — 用户启用 / 交互 / 限制 / FAQ
• docs/user/reference/configuration.md — execApprovals.{enabled, approvers} schema
• docs/releases/v3.6.4.md — 本期 release notes
• docs/features/2026-05-18-gap-01-approval-native-design.html — spec v3.12
• docs/plans/2026-05-19-gap-01-approval-native.md — 26 task plan v6

验证 TODO

已本地验证

• pnpm test:124 files passed,1265 tests passed
• pnpm run type-check:通过
• pnpm run lint:0 errors,87 warnings(全是 pre-existing,无新增)
• git diff --check:通过

真机验证

流程参 skills/dingtalk-real-device-testing/SKILL.md。每条 checklist 走"操作 → 预期结果",观察以 DingTalk 客户端肉眼为准,日志辅助。

环境准备

• ~/.openclaw/openclaw.json 插件路径指向当前 worktree
• pnpm run build:runtime && openclaw gateway restart
• openclaw channels status --probe --json 确认 running=true && connected=true(首次 probe 若撞上 restart 报 1006 abnormal closure,稍后再 probe)
• 配置 channels.dingtalk.execApprovals.approvers: ["<staffId-A>", "<staffId-B>"],并准备一个非 approver 账号

主路径 — 验证 approval 三按钮、markdown 模板、/approve 命令在常规分支上行为正确

• exec · 允许一次 — 群里触发需审批的 exec(如 rm 类) → AI Card 出现 3 按钮 → 点"允许一次" → 按钮消失,agent 继续流式,命令执行
• exec · 拒绝 — 同上 → 点"拒绝" → 按钮消失,agent 收到 deny 后停止该 exec
• exec · 总是允许 — 上游支持 always 时:后续同类 exec 自动跳过审批;不支持时:approver 私聊收到 invalid-decision 提示并列出可选 decisions
• markdown fallback — DM 中无 active card 时触发 plugin approval → 收到含 /approve <id> ... 命令模板的 markdown → approver 发 /approve <id> allow-once → 上游 resolve
• /approve 绕过 session lock — agent 长输出中,approver 在同会话发 /approve <id> allow-once → 命令早期拦截 resolve,agent 输出不打断
• 非 approver 点击 / 命令 — 私聊收到"无权"提示,卡片保持 pending,真正的 approver 仍可继续

异常路径 — 验证 harden 改动的兜底与重试语义

• gateway 临时错误 — 拔网 / kill openclaw gateway 期间点按钮 → 私聊收到"稍后重试",卡片保持 pending 不变 expired;恢复网络再点可正常 resolve
• 上游 TTL 过期 — approval 留到超时不点 → 按钮自动消失,hasAction 跟随 card 流式状态恢复
• 重启后旧按钮 — openclaw gateway restart 后点 restart 前发出的旧按钮 → 收到 not-found 兜底,卡片落 cleared 态,不留死按钮

回归 — 验证相邻既有路径不受 approval 改动影响

• AI Card 普通流式 — 无 approval 触发的普通对话,card 流式 + finalize 全程正常,approveId / show_approve_btns 不影响渲染
• stop button — agent 流式中点停止 → card 正常 finalize,actionId=btn_stop 不被 approval 分支误吞
• 普通 markdown / text 回复 — /approve 不误命中普通文本
• allowlist 隔离 — dmPolicy / groupPolicy / commands.ownerAllowFrom 既有语义不变;execApprovals.approvers 与 owner 名单独立(owner 不自动是 approver)

观测与收尾

• 实时日志:tail -n 0 -f ~/.openclaw/logs/gateway.log,关注 [DingTalk][Approval] / [DingTalk][Approval][DeliveryError]
• 结果回填本 PR 评论
• 按 SKILL.md 第 7 步还原 ~/.openclaw/openclaw.json 临时改动并 restart

[greptile-apps]

Greptile Summary

本 PR 实现了 GAP-01：将 DingTalk channel 接入 OpenClaw 原生审批能力（exec approval + plugin approval），新增 src/approval/ 域共 13 个模块（~900 LOC），并对 card-run-registry、card-callback-service、card-service、channel-gateway、inbound-handler 等既有文件做最小侵入式改动。配套集成测试覆盖 12 个关键场景，review 反馈（安全鉴权门前移、并发去重、重试语义）均已合入。

• 新增 approval 域：4 个 sub-adapter（availability / presentation / transport / observe）+ approval-resolver（鉴权门置于 plugin: 前缀判断之前）+ callback-handler + command-intercept，以及 card-locator / card-patcher / card-state / markdown-render 支撑模块。
• 双入口收敛：按钮回调（channel-gateway → tryHandleApprovalCallback）与 /approve 命令（inbound-handler session lock 前早期拦截 → tryInterceptApproveCommand）均汇聚到 resolveApproval → resolveApprovalOverGateway，retry 语义统一保留 pending + 私聊提示。
• 卡片生命周期：createAICard / commitAICardBlocks / finalizeStoppedAICard 三处写入 APPROVAL_CARD_INITIAL，approvalParamsForTerminal 在 pending 期间返回 {} 避免覆盖审批 UI 变量，approval patcher 为唯一写入方。

Confidence Score: 4/5

整体改动结构清晰、测试覆盖充分，存在一处卡片投递时 token 获取失败不会触发 markdown 降级的问题，修复后可安全合入。

deliverPending 中 getAccessToken 在 try 块外调用：当 DingTalk token 接口返回 HTTP 4xx 时，shouldFallbackToMarkdown 本应判定为可降级错误，但因异常在 try/catch 之前抛出，markdown 兜底路径被静默跳过，审批通知不会发出。其余逻辑（鉴权门、并发去重、重试语义、卡片状态）均已对齐 review 反馈，集成测试 12 场景覆盖率高。

src/approval/approval-native-runtime.ts 的 deliverPending 方法需要关注

Important Files Changed

Filename	Overview
src/approval/approval-native-runtime.ts	新增 DingTalk 审批 native runtime 四个 sub-adapter；deliverPending 中 getAccessToken 位于 try 块外，HTTP 4xx token 错误会跳过 markdown 降级路径直接抛出
src/approval/approval-resolver.ts	新增审批 resolve 核心逻辑；鉴权门正确置于 plugin: 前缀判断之前，gateway error 分类完整，无明显问题
src/approval/approval-callback-handler.ts	按钮回调入口，先 resolve 再 best-effort patch 卡片，gateway-error 保留 pending 语义，逻辑清晰
src/approval/approval-command-intercept.ts	/approve 命令拦截；APPROVE_COMMAND_RE 正斜杠可选问题已在上轮 review 讨论，本次无新问题
src/approval/approval-card-locator.ts	正确拒绝已有不同 pendingApprovalId 的 active card，并发场景下自动降级 markdown，逻辑正确
src/card-service.ts	三处（createAICard/commit/finalizeStopped）写入 APPROVAL_CARD_INITIAL，approvalParamsForTerminal 在 pending 时返回 {} 避免覆盖，设计合理
src/gateway/channel-gateway.ts	在 TOPIC_CARD listener 中先调 tryHandleApprovalCallback，handled=true 提前返回，stop button 等普通回调正常穿透，无问题
src/inbound-handler.ts	在 session lock 前早期拦截 /approve 命令，符合绕过 session lock 的设计意图
src/card/card-run-registry.ts	新增 isActiveCardRun/resolveActiveCardRunBySession/markCardRunPendingApproval/clearCardRunPendingApproval，复用现有 card 状态，无独立 store 引入
tests/integration/approval-end-to-end.test.ts	12 个端到端场景覆盖多 approver 竞争/非 approver/expired/markdown 降级等，但未覆盖 getAccessToken 在 deliverPending 中抛出的场景

Sequence Diagram

sequenceDiagram
    participant SDK as OpenClaw SDK
    participant Runtime as DingTalkApprovalNativeRuntime
    participant Locator as approval-card-locator
    participant Patcher as approval-card-patcher
    participant DT as DingTalk API

    SDK->>Runtime: availability.shouldHandle()
    Runtime-->>SDK: true/false

    SDK->>Runtime: transport.prepareTarget()
    Runtime->>Locator: findActiveAgentCard(sessionKey, approvalId)
    Locator-->>Runtime: card outTrackId 或 null
    Runtime-->>SDK: "target{route:card|markdown}"

    SDK->>Runtime: transport.deliverPending()
    alt "route = card"
        Runtime->>DT: getAccessToken() 在 try 块外
        Runtime->>Patcher: applyPendingPatch(outTrackId, approvalId)
        Patcher->>DT: "updateCardVariables(show_approve_btns=true)"
        alt HTTP 4xx
            Runtime->>DT: sendProactiveTextOrMarkdown(markdown)
        end
    else "route = markdown"
        Runtime->>DT: sendProactiveTextOrMarkdown(markdown)
    end

    note over DT: 用户点击审批按钮
    DT->>Gateway: TOPIC_CARD callback
    Gateway->>CallbackHandler: tryHandleApprovalCallback()
    CallbackHandler->>Resolver: resolveApproval(approvalId, decision, senderId)
    Resolver->>SDK: resolveApprovalOverGateway()
    SDK-->>Resolver: ok / error
    Resolver-->>CallbackHandler: ResolverResult
    CallbackHandler->>Patcher: patchCardBestEffort(applyResolvedPatch)
    Patcher->>DT: "updateCardVariables(show_approve_btns=false)"

    note over DT: 用户发送 /approve 命令
    DT->>InboundHandler: handleDingTalkMessage()
    InboundHandler->>Intercept: tryInterceptApproveCommand() session lock 前
    Intercept->>Resolver: resolveApproval(approvalId, decision, senderId)
    Resolver->>SDK: resolveApprovalOverGateway()

Loading

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
src/approval/approval-native-runtime.ts:153-173
`deliverPending` 中 `getAccessToken` 调用在 `try` 块之外：若 token 获取因 HTTP 4xx 失败，`shouldFallbackToMarkdown` 本可返回 `true` 并走 markdown 兜底，但由于异常在 `try` 之前抛出，catch 分支不会执行，markdown 降级路径被完全绕过，上游直接收到异常，审批通知静默丢失。将 `getAccessToken` 移入 `try` 块可在卡片接口 4xx 故障时正确触发 markdown 降级。

```suggestion
        if (preparedTarget.route === "card" && preparedTarget.activeCardOutTrackId) {
          try {
            const token = await getAccessToken(dtConfig, log);
            await applyPendingPatch(
              preparedTarget.activeCardOutTrackId,
              pendingPayload.approvalId,
              token,
              dtConfig,
            );
            return {
              mode: "card",
              approvalId: pendingPayload.approvalId,
              accountId: preparedTarget.accountId,
              outTrackId: preparedTarget.activeCardOutTrackId,
            };
          } catch (error) {
            if (!shouldFallbackToMarkdown(error)) {
              return null;
            }
          }
        }
```

_{Reviews (2): Last reviewed commit: "fix(approval): declare execApprovals in ..." | Re-trigger Greptile}

[greptile-apps]

updateEntry 中 getAccessToken、applyResolvedPatch 或 applyExpiredPatch 抛出异常时，错误会直接向上游 SDK 传播，没有任何 catch 处理。这与 approval-callback-handler.ts 中对同类操作使用 patchCardBestEffort（吞掉失败、仅打日志）的设计模式不一致。若 token 获取或卡片 patch 在审批已经通过后失败，上游可能无法区分是"卡片更新失败"还是"审批本身失败"，影响可观测性和重试语义。建议在 updateEntry 内部加 try/catch，捕获后仅记录 warn 日志，保持 best-effort 语义与其他路径对齐。

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/approval/approval-native-runtime.ts
Line: 190-210

Comment:
`updateEntry` 中 `getAccessToken`、`applyResolvedPatch` 或 `applyExpiredPatch` 抛出异常时，错误会直接向上游 SDK 传播，没有任何 catch 处理。这与 `approval-callback-handler.ts` 中对同类操作使用 `patchCardBestEffort`（吞掉失败、仅打日志）的设计模式不一致。若 token 获取或卡片 patch 在审批已经通过后失败，上游可能无法区分是"卡片更新失败"还是"审批本身失败"，影响可观测性和重试语义。建议在 `updateEntry` 内部加 `try/catch`，捕获后仅记录 warn 日志，保持 best-effort 语义与其他路径对齐。

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

deliverPending 中 getAccessToken 调用在 try 块之外：若 token 获取因 HTTP 4xx 失败，shouldFallbackToMarkdown 本可返回 true 并走 markdown 兜底，但由于异常在 try 之前抛出，catch 分支不会执行，markdown 降级路径被完全绕过，上游直接收到异常，审批通知静默丢失。将 getAccessToken 移入 try 块可在卡片接口 4xx 故障时正确触发 markdown 降级。

Suggested change

	if (preparedTarget.route === "card" && preparedTarget.activeCardOutTrackId) {
	const token = await getAccessToken(dtConfig, log);
	try {
	await applyPendingPatch(
	preparedTarget.activeCardOutTrackId,
	pendingPayload.approvalId,
	token,
	dtConfig,
	);
	return {
	mode: "card",
	approvalId: pendingPayload.approvalId,
	accountId: preparedTarget.accountId,
	outTrackId: preparedTarget.activeCardOutTrackId,
	};
	} catch (error) {
	if (!shouldFallbackToMarkdown(error)) {
	return null;
	}
	}
	}
	if (preparedTarget.route === "card" && preparedTarget.activeCardOutTrackId) {
	try {
	const token = await getAccessToken(dtConfig, log);
	await applyPendingPatch(
	preparedTarget.activeCardOutTrackId,
	pendingPayload.approvalId,
	token,
	dtConfig,
	);
	return {
	mode: "card",
	approvalId: pendingPayload.approvalId,
	accountId: preparedTarget.accountId,
	outTrackId: preparedTarget.activeCardOutTrackId,
	};
	} catch (error) {
	if (!shouldFallbackToMarkdown(error)) {
	return null;
	}
	}
	}

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/approval/approval-native-runtime.ts
Line: 153-173

Comment:
`deliverPending` 中 `getAccessToken` 调用在 `try` 块之外：若 token 获取因 HTTP 4xx 失败，`shouldFallbackToMarkdown` 本可返回 `true` 并走 markdown 兜底，但由于异常在 `try` 之前抛出，catch 分支不会执行，markdown 降级路径被完全绕过，上游直接收到异常，审批通知静默丢失。将 `getAccessToken` 移入 `try` 块可在卡片接口 4xx 故障时正确触发 markdown 降级。

```suggestion
        if (preparedTarget.route === "card" && preparedTarget.activeCardOutTrackId) {
          try {
            const token = await getAccessToken(dtConfig, log);
            await applyPendingPatch(
              preparedTarget.activeCardOutTrackId,
              pendingPayload.approvalId,
              token,
              dtConfig,
            );
            return {
              mode: "card",
              approvalId: pendingPayload.approvalId,
              accountId: preparedTarget.accountId,
              outTrackId: preparedTarget.activeCardOutTrackId,
            };
          } catch (error) {
            if (!shouldFallbackToMarkdown(error)) {
              return null;
            }
          }
        }
```

How can I resolve this? If you propose a fix, please make it concise.

[zhumin-zizhu]

结论:暂停本 PR —— 根因是上游 openclaw bug,不在本插件可修范围

经过真机调试 + 四轮上游 openclaw 探针,gap #1 原生审批「点按钮永远 unknown or expired」的根因已 100% 钉死,不是本 channel 插件的缺陷,而是上游 openclaw 的一个进程级共享密钥被 module graph 复制成两份导致的。本 PR 在上游修复前无法真正打通,故暂停。

前因后果

现象:DingTalk 审批卡片正常投递,但点 Allow/Deny 按钮永远返回 unknown or expired approval id;同服务器、同网关、同 exec 审批配置下 Telegram 原生审批完整 work。

排查中被证伪的假设:

• ❌ callback 解码 / approvalId 错误 —— approvalId 正确。
• ❌ turnSourceAccountId 传播链丢值 —— 探针实测 turnSourceChannel=dingtalk turnSourceAccountId=default,完全正确。
• ❌ 上游 no-approval-route 短路 —— 探针实测该分支根本没进(hasApprovalClients=true、surfaceKind=enabled)。
• ❌ 审批被提前 expire —— ExecApprovalManager 探针实测审批 register timeoutMs=30min 后全程无 expire/resolve,一直存活。

真正的根因:

1. unknown or expired 是上游 isApprovalRecordVisibleToClient 可见性判定的伪装错误 —— 审批其实一直活着,只是 resolve 连接被判「无权看见」。
2. 可见性判定要求 resolve 连接带 internal.approvalRuntime===true;该标记由网关握手时 isTrustedApprovalRuntime 决定。
3. 探针实测:点按钮的 resolve 连接 scopes=["operator.approvals"] ✓、clientId/mode ✓,唯独 approvalRuntimeToken 校验 tokenValid=false(token 已带、43 字符,但值与网关不符)。
4. 源头:operator-approval-runtime-token.ts 的 approvalRuntimeToken 是模块级懒加载随机单例(token ??= randomBytes(32))。外部 channel extension 调 resolveApprovalOverGateway(openclaw/plugin-sdk/approval-gateway-runtime)运行在独立的 module graph 实例,自行 mint 了一个 token;网关核心是另一个实例、另一个 token。两者不匹配 → resolve 连接拿不到 approvalRuntime 标记 → 可见性判定失败。
5. Telegram 是内置频道,resolve 跑在网关核心同一 module graph,token 一致,故 work;DingTalk 是外部 extension,token 分叉,故必坏。

关键证据(上游 host openclaw 探针,真机 2026-05-20)

MGR.register id=… timeoutMs=1800000        # 审批注册,30 分钟存活,无 expire/resolve
VIS … approvalRuntime=undefined            # resolve 连接缺 approvalRuntime 标记
HANDSHAKE … tokenPresent=true tokenLen=43 tokenValid=false isTrustedApprovalRuntime=false

修复方向(归属上游 openclaw)

getOperatorApprovalRuntimeToken() 应把 token 存为真正的进程级单例(globalThis / 环境变量 / 文件),而非模块级 let —— 这样跨 module graph 共享同一 token。否则任何外部 channel extension 的原生审批 resolve 都会同样失败。建议上游开 issue/PR;本插件 PR 待上游修复后再恢复。