配置项参考

本页汇总常用配置项及其作用。更完整的场景说明请结合功能页一起阅读。

主要配置项

选项	类型	默认值	说明
`enabled`	boolean	`true`	是否启用插件
`clientId`	string	必填	钉钉 AppKey；同时作为钉钉 API 请求中的 `robotCode`
`clientSecret`	string \| SecretInput	必填	钉钉 AppSecret；可直接填写字符串，也可引用环境变量或文件
`dmPolicy`	string	`open`	私聊策略
`groupPolicy`	string	`open`	群聊策略
`allowFrom`	string[]	`[]`	私聊白名单
`groupAllowFrom`	string[]	-	群聊发送者白名单
`groups`	object	-	群级配置
`displayNameResolution`	string	`disabled`	是否允许基于本地目录做显示名解析
`contextVisibility`	string	宿主默认值	是否限制宿主补充上下文、引用上下文与历史上下文的可见性
`bypassProxyForSend`	boolean	`false`	发送链路是否绕过全局代理
`learningEnabled`	boolean	`false`	是否开启学习信号采集
`learningAutoApply`	boolean	`false`	是否自动注入学习结果
`learningNoteTtlMs`	number	`21600000`	会话级学习笔记 TTL
`mediaUrlAllowlist`	string[]	`[]`	允许下载的远程媒体目标
`journalTTLDays`	number	`7`	引用回溯日志保留天数
`ackReaction`	string	-	原生处理中表情反馈
`messageType`	string	`markdown`	回复模式：`markdown` 或 `card`
`cardTemplateId`	string	-	已弃用。AI 卡片模板 ID 由预置模板固定，如需覆盖可通过环境变量 `DINGTALK_CARD_TEMPLATE_ID`
`cardTemplateKey`	string	`content`	卡片内容字段名
`cardStreamingMode`	string	`off`（生效值）	卡片流式模式：`off` / `answer` / `all`
`cardStreamInterval`	number	`1000`	卡片实时更新节奏（毫秒，最小 `200`）
`outboundSendIntervalMs`	number	`1000`	同一会话内两次出站消息之间的最小间隔（毫秒，`0`–`10000`）；`0` 关闭节流
`cardTaskProgress`	boolean	未设置时开启	长任务进度块；`false` 关闭，`true` 强制开启（含显式 `cardStreamingMode: "off"`）
`cardTaskProgressRefresh`	string	`heartbeat`	进度块刷新节奏：`heartbeat`（每 30 秒，调用量固定）/ `interval`（每次工具事件，受 `cardStreamInterval` 节流）
`cardAtSender`	string	-	群聊中卡片完成后追加 @发送者的消息文本；非空时生效
`cardRealTimeStream`	boolean	`false`	已弃用；仅兼容旧配置，`true` 会回退到 `cardStreamingMode: all`
`aicardDegradeMs`	number	`1800000`	卡片连续失败后的降级时间
`debug`	boolean	`false`	是否输出调试日志
`mediaMaxMb`	number	-	入站媒体大小上限
`maxConnectionAttempts`	number	`10`	最大连接重试次数
`initialReconnectDelay`	number	`1000`	初始重连延迟
`maxReconnectDelay`	number	`60000`	最大重连延迟
`reconnectJitter`	number	`0.3`	重连抖动因子
`gatewayCapabilities`	object	-	Gateway RPC 能力开关与白名单：`tools.docs` / `tools.proactiveSend` / `docs.allowedSpaceIds` / `send.allowedTargets`；默认全部开启

关于 `clientId` 与钉钉 `robotCode`

钉钉开放接口的请求体里仍会携带 robotCode 字段。本插件不提供单独的 robotCode、corpId 或钉钉应用 agentId 配置项：clientId 会作为机器人代码用于相关 API 调用。

关于 `clientSecret` 与 SecretInput

clientSecret 可以继续使用普通字符串：

json5

{
  "clientId": "dingxxxxxx",
  "clientSecret": "your-app-secret"
}

也可以使用 SecretInput 引用：

json5

{
  "clientId": "dingxxxxxx",
  "clientSecret": {
    "source": "env",
    "provider": "env",
    "id": "DINGTALK_CLIENT_SECRET"
  }
}

SecretInput 对象字段：

字段	说明
`source`	密钥来源：`env` 或 `file`
`provider`	`secrets.providers` 中已配置的宿主 provider 名称
`id`	provider 内的密钥标识；`env` 为允许的环境变量名，`file` 的 `singleValue` 模式固定为 `value`

注意：v3.6.2 起，source 只支持 env 和 file，不再支持 exec（已移除进程执行路径以通过 OpenClaw 安装安全扫描）。

语法限制：

provider 不能为空，最长 1024 字符，不能包含 : 或 >
id 不能为空，最长 1024 字符，不能包含 >
provider 的路径、权限和允许范围由 OpenClaw 宿主配置管理

解析时机：

获取 DingTalk access token 时，如果 token 缓存未命中，会解析 clientSecret
启动 Stream 连接时，会为每个账号解析一次运行时凭据
状态展示、配置向导展示等路径只显示规范化引用，不会解析密钥

安全边界：

env 引用通过宿主只读路径授权校验后才读取：插件把引用交给宿主 SDK 的 resolveReadOnlyEnvSecretRef，由宿主读取该引用对应的单个环境变量；插件自身不访问进程环境，也不会把整个 process.env 交给任何解析器
授权规则与宿主一致：
- secrets.providers.<provider> 声明为 source: "env" 且 allowlist 包含该 id → 授权通过
- secrets.providers.<provider> 声明为 source: "env" 但未配置 allowlist → 该 provider 会对任意 id 放行，等效于不做白名单限制
- provider 指向内置默认 env provider（未声明 secrets.providers 中的同名项）→ 按宿主内置默认规则判定
- 以上都不满足 → 判定为未授权，插件在发起任何 DingTalk 请求前抛本地错误
强烈建议显式配置 allowlist：省略它会让该 provider 授权所有环境变量，等于放弃白名单边界
授权通过但对应环境变量未设置或为空 → 判定为未解析，失败原因会区分“未授权”与“已授权但未设置”，便于定位
file 引用由 secrets.providers 的文件 provider 读取，插件不会把 id 当作本地路径
文件 Provider 的路径与权限要求由 OpenClaw 宿主校验（2026.8 起不再接受 allowInsecurePath，密钥文件应放在受信状态目录下）

宿主版本要求：本改动使用了 OpenClaw 2026.8.1 起提供的 openclaw/plugin-sdk/secret-ref-readonly。宿主版本低于 2026.8.1 时插件无法加载，请先升级 OpenClaw 宿主。

如果 SecretInput 解析失败，插件会在发起 DingTalk API 请求前抛出本地错误，并在日志中带上 source / provider / id / 失败原因，方便定位配置问题。

关于 `displayNameResolution`

disabled：默认值，只允许显式 ID
all：允许本地学习目录参与群名和显示名解析

启用后要注意两类风险：

误投风险：重名、改名、旧目录数据都可能导致误解析
权限扩散风险：当前没有 owner-only 粒度

对敏感通知和不可撤回消息，建议优先使用显式 ID。

关于 `contextVisibility`

all：沿用宿主当前的补充上下文行为
allowlist：只保留宿主 allowlist 范围内的补充上下文
allowlist_quote：优先保留显式引用 / 回复上下文，同时过滤额外补充上下文

如果你只想让模型看到“用户明确引用的那条消息”，通常 allowlist_quote 是最稳妥的高级模式。

它和 displayNameResolution 的职责不同：

contextVisibility 控制“宿主把多少上下文送进 reply runtime”
displayNameResolution 控制“插件是否允许根据本地学习目录解析群名或显示名”

前者影响模型可见上下文，后者影响目标解析与投递安全；两者不要混用。

关于 `ackReaction`

启用后，插件会在处理开始时对用户原消息添加原生文本表情反馈，处理结束后自动撤回。

常见配置：

""：关闭
"🤔思考中"：固定“思考中”
"emoji"：使用固定 emoji 模式
"kaomoji"：按输入语气选择颜文字

关于 `cardStreamingMode` / `cardRealTimeStream` / `cardStreamInterval` / `cardTaskProgress`

cardStreamingMode=off：关闭答案实时流式，增量更新最少。
cardStreamingMode=answer：只实时推送答案内容。
cardStreamingMode=all：答案片段实时推送到 content key；思考/工具内容实时更新 block 列表，答案在边界或结束时固化到 block 列表。
cardRealTimeStream 已弃用，仅保留兼容：
未设置 cardStreamingMode 且 cardRealTimeStream=true 时，生效为 all。
同时设置时，以 cardStreamingMode 为准。
cardStreamInterval 控制实时更新节奏（毫秒），在 answer / all 下生效；值越小，更新越频繁，API 调用通常越高。
cardTaskProgress 控制长任务进度块：未设置时默认开启，但 cardStreamingMode 显式为 off 时默认关闭；设为 true 可在 off 下仍然开启，设为 false 则完全关闭。详见 AI 卡片。
cardTaskProgressRefresh 控制进度块的刷新节奏：默认 heartbeat，只有首次出现立即推送，之后每 30 秒刷新一次，调用量可预测；设为 interval 则每次可关联的工具事件都推送一次（受 cardStreamInterval 节流），数字更新更及时但调用量随工具调用次数增长。

关于连接参数

连接相关配置用于提升 Stream 连接鲁棒性：

最大尝试次数
指数退避延迟
随机抖动
发送链路代理绕过

关于上游群聊默认行为

OpenClaw 2026.5.7 之后，群聊默认 messages.groupChat.visibleReplies=message_tool 会将 source reply delivery 解析为 message_tool_only。这对普通群聊消息是合理默认，但 DingTalk 插件的 card / markdown / sessionWebhook strategy 本身就是可见回复承载面。

插件已从 v3.6.2 起在 card 和 markdown/sessionWebhook reply strategy 中显式声明 sourceReplyDeliveryMode: "automatic"（PR #553、PR #565），确保 final answer 回到正确的回复策略路径，不会被上游默认值误导向 message tool。

用户无需额外配置。如果你在群聊中观察到回复丢失或出现空卡片 + 额外 fallback 消息，请确认插件版本不低于 v3.6.2。

关于 `gatewayCapabilities`

gatewayCapabilities 收窄 Gateway RPC 的影响面（Issue #608 问题 3），全部默认开启、不配置即保持现有行为：

gatewayCapabilities.tools.docs / gatewayCapabilities.tools.proactiveSend：分别关闭全部 docs RPC（dingtalk.docs.* 与 dingtalk-connector.docs.*）与全部主动发送 RPC（dingtalk-connector.sendToUser/sendToGroup/send）。
gatewayCapabilities.docs.allowedSpaceIds：文档空间白名单；配置后不携带 spaceId 的请求（例如 docs.append）也会被拒绝。
gatewayCapabilities.send.allowedTargets：主动发送目标白名单，每项为 user:<id> 或 group:<conversationId>。
白名单配置后至少需要一项，空数组会被配置校验拒绝；多账号下账号级 gatewayCapabilities 与渠道级按子键合并，渠道级限制不会被账号级局部配置静默移除。

这些 RPC 依赖宿主 Gateway 的信任模型（插件层不做二次调用方身份认证），完整说明、拒绝行为与所需钉钉权限见 Gateway RPC 兼容层。

配置项参考 ​

主要配置项 ​

关于 clientId 与钉钉 robotCode ​

关于 clientSecret 与 SecretInput ​

关于 displayNameResolution ​

关于 contextVisibility ​

关于 ackReaction ​

关于 cardStreamingMode / cardRealTimeStream / cardStreamInterval / cardTaskProgress ​

关于连接参数 ​

关于上游群聊默认行为 ​

关于 gatewayCapabilities ​

相关文档 ​