OpenClaw 钉钉机器人接入指南:企业内部应用、Stream 长连接与流式 AI Card 实战

原创2026-10-03 22:13:111,757 阅读
文章标签:人工智能AI Agent多智能体交互助手AI 技能AI 插件本地部署API网关语音CLI

OpenClaw 钉钉机器人接入指南:企业内部应用、Stream 长连接与流式 AI Card 实战

钉钉(DingTalk)是 OpenClaw 中文社区版内置支持的官方聊天渠道之一,本文围绕 钉钉机器人渠道文档 展开,完整讲解从钉钉开放平台创建企业内部应用、在 OpenClaw 中安装官方连接器、配置凭证与访问策略,到通过 Stream 长连接接收消息并以流式 AI Card 实时回复的端到端流程。读完本文,你将掌握 openclaw-cn channels add、openclaw-cn pairing approve、多 Agent 路由绑定等核心操作,并能独立排查机器人不响应、Token 认证失败等常见问题。


核心特性一览

钉钉渠道在 OpenClaw 中属于生产就绪(production-ready)状态,支持机器人私聊与群组对话,其主要特性包括:

  • 官方连接器接入:通过官方 @dingtalk-real-ai/dingtalk-connector 插件接入钉钉机器人,中文社区版提供同名包装插件(见 extensions/dingtalk-connector/package.json)。
  • Stream 长连接模式:无需公网服务器,钉钉主动通过长连接把消息推送到本地网关,适合个人与家庭环境部署。
  • 流式 AI Card 回复:回复以 AI Card 卡片形式呈现,支持实时打字机效果。
  • 确定性路由:回复始终返回钉钉渠道,模型不会自行选择输出渠道。
  • 会话隔离:私聊共享主会话;群组之间相互独立隔离。

从渠道注册表看,dingtalk-connector 在 src/channels/registry.ts 中被注册为核心聊天渠道之一,并支持 dingtalk、dingding 两个别名(见 src/channels/registry.ts),在 CLI 与配置中均可使用。


快速开始:两种添加方式

添加钉钉渠道有两种途径,均可完成插件安装、凭证录入与网关配置。

方式一:通过安装向导添加(推荐)

如果刚完成 OpenClaw 安装,直接运行向导:

openclaw-cn onboard

向导会引导你依次完成:

  1. 安装官方钉钉插件;
  2. 输入应用 Client ID 与 Client Secret;
  3. 输入 Gateway Token;
  4. 启动网关。

配置完成后,用以下命令检查网关状态:

  • openclaw-cn gateway status —— 查看网关运行状态;
  • openclaw-cn logs --follow —— 实时查看日志。

方式二:通过命令行添加

已完成初始安装的用户,可以直接运行:

openclaw-cn channels add

在交互式提示中选择 钉钉 (官方连接器),按提示输入三个必填参数即可。插件元数据中的 selectionLabel 正是“钉钉 (官方连接器)”,见 extensions/dingtalk-connector/src/channel.ts。

配置完成后:

  • openclaw-cn gateway status —— 查看网关运行状态;
  • openclaw-cn gateway restart —— 重启网关以应用新配置;
  • openclaw-cn logs --follow —— 实时查看日志。

第一步:创建钉钉企业内部应用

钉钉机器人依托“企业内部应用”运行,需要企业管理员或开发者权限。

1. 打开钉钉开放平台

访问钉钉开放平台开发者后台,使用钉钉账号(需企业管理员或开发者权限)登录。

2. 创建企业内部应用

  1. 点击左侧菜单 应用开发 > 企业内部开发;
  2. 点击 创建应用;
  3. 选择 钉钉应用,填写应用名称和描述。

钉钉开放平台创建企业内部应用

3. 获取应用凭证

进入应用详情页,在 基础信息 页面复制:

  • Client ID(即 AppKey,格式如 dingxxxxxx);
  • Client Secret(即 AppSecret)。

注意:请妥善保管 Client Secret,不要分享给他人。AppKey/AppSecret 不要混淆。

获取钉钉应用 Client ID 与 Client Secret

4. 开启机器人能力

在应用详情页进入 添加应用能力 > 机器人:

  1. 点击 添加 开启机器人能力;
  2. 在机器人配置中填写机器人名称和描述;
  3. 消息接收模式 选择 Stream 模式(无需公网服务器,这是 OpenClaw 本地网关能直接接收消息的关键前提)。

开启钉钉机器人能力并选择 Stream 消息接收模式

5. 配置权限

在 权限管理 页面,搜索并添加以下三个必要权限:

权限名称 说明
Card.Streaming.Write 向 AI Card 推送流式内容(打字机效果必需)
Card.Instance.Write 创建和更新 AI Card 实例
qyapi_robot_sendmsg 机器人发送消息

提示:根据实际需求,可能还需要添加文档读写等其他权限(例如让 Agent 读写钉钉文档)。

6. 发布应用

  1. 在 版本管理与发布 页面点击 创建新版本;
  2. 填写版本说明后提交;
  3. 选择应用可见范围(建议先设为 全员 进行测试);
  4. 点击 确认发布。

只有发布后的应用才能被机器人服务正常调用,未发布的应用在后续测试阶段会出现“机器人不响应”等异常。


第二步:配置 OpenClaw

通过向导配置(推荐)

运行:

openclaw-cn channels add

选择 钉钉 (官方连接器),然后按提示安装官方插件并输入凭证。交互过程大致如下:

◇  安装 钉钉 插件?
│  钉钉官方插件

◇  输入钉钉应用 Client ID
│  dingxxxxxxxxxxxxxx

◇  输入钉钉应用 Client Secret
│  xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

◇  输入 Gateway 认证 Token(openclaw.json 中 gateway.auth.token 的值)
│  your-gateway-token

Gateway Token 说明:钉钉官方插件通过 HTTP 请求本地 Gateway,需要认证 Token。如果尚未配置 gateway.auth.token,可以先设置一个随机字符串(例如运行 openssl rand -hex 16 生成),在两处填写相同的值即可。

从 extensions/dingtalk-connector/src/onboarding.ts 的实现看,向导的 configure 流程会:以已有配置为 initialValue 预填 Client ID / Client Secret / Gateway Token;若未单独配置过 gatewayToken,则自动回退读取 gateway.auth.token 作为默认值。提交后,applyDingtalkConnectorConfig 会做三件事(见 extensions/dingtalk-connector/src/onboarding.ts):

  1. 写入 channels.dingtalk-connector 下的 clientId、clientSecret、gatewayToken,并置 enabled: true;
  2. 强制打开 gateway.http.endpoints.chatCompletions.enabled = true(这是连接器调用本地网关所必需);
  3. 若 gateway.auth.mode 未设置则设为 "token",若 gateway.auth.token 未设置则写入刚输入的 Gateway Token。

也就是说,向导会在你输入凭证的同时,自动补齐网关侧认证与 HTTP 端点的配套配置,避免漏配导致 401。

通过配置文件配置

编辑 ~/.openclaw/openclaw.json:

{
  "channels": {
    "dingtalk-connector": {
      "enabled": true,
      "clientId": "dingxxxxxxxxxxxxxx",
      "clientSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "gatewayToken": "your-gateway-token",
      "dmPolicy": "pairing"
    }
  },
  "gateway": {
    "auth": {
      "mode": "token",
      "token": "your-gateway-token"
    },
    "http": {
      "endpoints": {
        "chatCompletions": {
          "enabled": true
        }
      }
    }
  }
}

重要:channels.dingtalk-connector.gatewayToken 必须与 gateway.auth.token 保持一致,官方插件通过此 Token 验证 Gateway 身份。同时必须开启 gateway.http.endpoints.chatCompletions.enabled,否则连接器无法把消息转发给本地网关处理。

除了上述字段,插件配置 Schema 还允许 gatewayPassword(备用网关密码)与 sessionTimeout(会话超时,非负整数)两个可选字段,见 extensions/dingtalk-connector/src/channel.ts;enabled、clientId、clientSecret 均为常规必填/可选字段。插件通过 reload.configPrefixes: ["channels.dingtalk-connector"] 声明,因此修改该配置前缀下的内容即可触发热重载,无需手动重建配置。


第三步:启动并测试

1. 启动网关

openclaw-cn gateway

2. 验证连接

启动后查看日志,确认钉钉 Stream 连接成功:

openclaw-cn logs --follow

正常启动日志应包含:

[dingtalk-connector] [__default__] 启动钉钉 Stream 客户端...
[dingtalk-connector] [__default__] 钉钉 Stream 客户端已连接

插件在运行时以固定账号 default 运行(defaultAccountId: () => "default",见 extensions/dingtalk-connector/src/channel.ts),因此日志中的 [__default__] 是预期输出。

3. 发送测试消息

在钉钉中搜索机器人名称找到刚创建的机器人,发送一条消息。

4. 配对授权

默认情况下(dmPolicy: "pairing"),机器人会回复一个 配对码。你需要批准此代码:

openclaw-cn pairing approve dingtalk-connector <配对码>

该命令的用法与参数约束定义在 src/cli/pairing-cli.ts,支持 pairing approve <channel> <code> 与 pairing approve --channel <channel> <code> 两种形式。批准后即可正常对话,机器人将以流式 AI Card 形式实时输出回复。


访问控制

私聊访问

  • 默认:dmPolicy: "pairing",陌生用户会收到配对码;
  • 批准配对:
    openclaw-cn pairing list dingtalk-connector      # 查看待审批列表
    openclaw-cn pairing approve dingtalk-connector <CODE>  # 批准
    
  • 白名单模式:通过 channels.dingtalk-connector.allowFrom 配置允许的用户 staffId。

群组访问

群组策略(channels.dingtalk-connector.groupPolicy):

  • "open" —— 允许群组中所有人(默认);
  • "allowlist" —— 仅允许 groupAllowFrom 中的用户;
  • "disabled" —— 禁用群组消息。

获取用户 staffId

钉钉侧的访问控制(白名单、多 Agent 绑定)都依赖用户的 staffId,可通过以下方式获取:

方法一(推荐):

  1. 启动网关并给机器人发消息;
  2. 运行 openclaw-cn logs --follow 查看日志中的 senderStaffId 字段。

方法二:

查看配对请求列表:

openclaw-cn pairing list dingtalk-connector

配对请求列表中同样包含发起配对用户的 staffId。


常用命令

命令 说明
/status 查看机器人状态
/reset 重置对话会话
/model 查看/切换模型

网关管理命令

命令 说明
openclaw-cn gateway status 查看网关运行状态
openclaw-cn gateway install 安装/启动网关服务
openclaw-cn gateway stop 停止网关服务
openclaw-cn gateway restart 重启网关服务
openclaw-cn logs --follow 实时查看日志输出

故障排除

机器人不响应消息

  1. 确认 Stream 连接已建立:查看日志是否有 钉钉 Stream 客户端已连接;
  2. 确认应用已发布且机器人能力已开启;
  3. 确认消息接收模式为 Stream 模式(而非 HTTP 回调);
  4. 查看日志:openclaw-cn logs --follow。

Gateway Token 认证失败

错误日志包含 401 或 认证失败 时:

  1. 确认 channels.dingtalk-connector.gatewayToken 与 gateway.auth.token 相同;
  2. 确认 gateway.http.endpoints.chatCompletions.enabled: true(连接器依赖该 HTTP 端点把钉钉消息转交本地网关);
  3. 重新运行配置向导更新凭证:openclaw-cn channels add(向导会自动补齐上述两处配置)。

Client ID / Client Secret 错误

  1. 在钉钉开放平台检查应用状态是否为已发布;
  2. 重新复制 Client ID 和 Client Secret(注意不要混淆 AppKey/AppSecret);
  3. 更新配置:openclaw-cn channels add,重新选择钉钉并输入正确凭证。

机器人在群组中不响应

  1. 确认机器人已被添加到该群组;
  2. 确认 groupPolicy 不为 "disabled";
  3. 在群组中 @ 机器人后发送消息(默认需要 @);
  4. 查看日志:openclaw-cn logs --follow。

Client Secret 泄露怎么办

  1. 在钉钉开放平台重置 Client Secret;
  2. 运行 openclaw-cn channels add 重新配置;
  3. 重启网关。

高级配置:多 Agent 路由

通过 bindings 配置,可以用一个钉钉机器人对接多个不同功能的 Agent。例如,私聊交给 main Agent,某个群组交给独立的 assistant Agent:

{
  "agents": {
    "list": [
      { "id": "main" },
      {
        "id": "assistant",
        "workspace": "~/assistant-workspace"
      }
    ]
  },
  "bindings": [
    {
      "agentId": "main",
      "match": {
        "channel": "dingtalk-connector",
        "peer": {
          "kind": "dm",
          "id": "staff_id_xxx"
        }
      }
    },
    {
      "agentId": "assistant",
      "match": {
        "channel": "dingtalk-connector",
        "peer": {
          "kind": "group",
          "id": "group_id_xxx"
        }
      }
    }
  ]
}

匹配规则说明:

字段 说明
agentId 目标 Agent 的 ID,需要在 agents.list 中定义
match.channel 渠道类型,固定为 "dingtalk-connector"
match.peer.kind 对话类型:"dm"(私聊)或 "group"(群组)
match.peer.id 用户 staffId 或群组 conversationId

完整配置示例

{
  "channels": {
    "dingtalk-connector": {
      "enabled": true,
      "clientId": "dingxxxxxxxxxxxxxxxxxx",
      "clientSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "gatewayToken": "your-gateway-token",
      "dmPolicy": "pairing",
      "groupPolicy": "open",
      "allowFrom": ["staff_id_xxx"],
      "groupAllowFrom": ["staff_id_xxx", "staff_id_yyy"]
    }
  },
  "gateway": {
    "auth": {
      "mode": "token",
      "token": "your-gateway-token"
    },
    "http": {
      "endpoints": {
        "chatCompletions": {
          "enabled": true
        }
      }
    }
  }
}

配置参考

配置项 说明 默认值
channels.dingtalk-connector.enabled 启用/禁用渠道 true
channels.dingtalk-connector.clientId 应用 Client ID(AppKey) -
channels.dingtalk-connector.clientSecret 应用 Client Secret(AppSecret) -
channels.dingtalk-connector.gatewayToken Gateway 认证 Token -
channels.dingtalk-connector.dmPolicy 私聊策略 pairing
channels.dingtalk-connector.allowFrom 私聊白名单(staffId 列表) -
channels.dingtalk-connector.groupPolicy 群组策略 open
channels.dingtalk-connector.groupAllowFrom 群组白名单 -
gateway.auth.mode 网关认证模式 -
gateway.auth.token 网关认证 Token -
gateway.http.endpoints.chatCompletions.enabled 启用 HTTP Chat Completions false

补充(来自插件 Schema):除上表字段外,插件配置还支持 gatewayPassword(备用密码)与 sessionTimeout(会话超时秒数,最小值 0),字段定义见 extensions/dingtalk-connector/src/channel.ts。


dmPolicy 策略说明

值 行为
"pairing" 默认。未知用户收到配对码,管理员批准后才能对话
"allowlist" 仅 allowFrom 列表中的用户可对话,其他静默忽略
"open" 允许所有人对话(需在 allowFrom 中加 "*")
"disabled" 完全禁止私聊

支持的消息类型

接收

  • ✅ 文本消息
  • ✅ 图片
  • ✅ 文件
  • ✅ 音频
  • ✅ 视频
  • ✅ @提及

发送

  • ✅ 流式 AI Card(实时打字机效果)
  • ✅ 文本消息
  • ✅ 图片
  • ✅ 文件
  • ✅ 音频
  • ✅ 视频

需要说明的是,从插件 capabilities 声明看(见 extensions/dingtalk-connector/src/channel.ts),该渠道当前不启用投票、线程、原生命中命令、表情回应与消息编辑等扩展能力,核心定位是可靠的文本/多媒体对话与流式卡片回复。


小结

钉钉渠道为 OpenClaw 中文社区版提供了一条零公网服务器依赖的接入路径:钉钉侧选择 Stream 消息接收模式,OpenClaw 侧通过官方 @dingtalk-real-ai/dingtalk-connector 连接器建立长连接,配合本地网关的 chatCompletions HTTP 端点完成消息转发,最终以流式 AI Card 呈现实时回复。整个接入过程只需完成“开放平台创建应用 → 向导填写三凭证 → 启动网关 → 配对批准”四个环节;上线后可通过 dmPolicy、groupPolicy、allowFrom 精确控制谁能与你的专属 AI 助手对话,也能借助 bindings 让同一个机器人按私聊/群组路由到不同 Agent。相关配置样例、源码实现与插件声明均可在 docs/channels/dingtalk-connector.md、extensions/dingtalk-connector/src/channel.ts、extensions/dingtalk-connector/src/onboarding.ts 与 src/channels/registry.ts 中进一步查阅。

登录后查看全文
openclaw-cn