ClawCN - OpenClaw 中文站

主题

钉钉应用配置详解 ​

本文档详细介绍如何在钉钉开放平台创建和配置应用，以及钉钉通道的访问控制设置。这是 Docker Compose + 钉钉部署指南 的配套文档。

创建钉钉应用 ​

1. 登录钉钉开放平台 ​

访问 钉钉开放平台 并使用管理员账号登录。

提示：如果您的组织尚未在钉钉开放平台注册，需要先完成企业认证。只有经过认证的企业才能创建企业内部应用。

2. 创建企业内部应用 ​

  1. 在开放平台首页，点击 应用开发 → 企业内部开发
  2. 点击 创建应用
  3. 填写应用基本信息：
    • 应用名称（如 "OpenClaw Bot"）
    • 应用描述（如 "OpenClaw AI 助手"）
    • 应用图标（上传自定义图标或使用默认图标）
  4. 选择应用类型为 机器人

提示：应用名称将显示在钉钉聊天列表中，建议使用简短易识别的名称。

3. 获取凭据 ​

在应用的 凭证与基础信息 页面，获取以下信息并填入 .env 文件：

  • Client ID（即 AppKey，应用的唯一标识）— 对应 .env 中的 DINGTALK_CLIENT_ID
  • Client Secret（即 AppSecret，应用密钥）— 对应 .env 中的 DINGTALK_CLIENT_SECRET
  • Robot Code（机器人代码，与 Client ID 相同）— 对应 .env 中的 DINGTALK_ROBOT_CODE
  • Corp ID（企业 ID，在"企业信息"页获取）— 对应 .env 中的 DINGTALK_CORP_ID
  • Agent ID（应用 ID）— 对应 .env 中的 DINGTALK_AGENT_ID

重要：Client Secret 必须保密，切勿泄露。泄露可能导致他人冒充您的应用发送消息。

4. 配置权限 ​

在 权限管理 中，手动开启所需的 API 权限。

注意：与飞书不同，钉钉不支持 JSON 批量导入权限。您需要在权限管理页面逐项搜索并手动开启每个权限。

插件必需权限：

权限名称权限代码说明
创建和投放卡片实例Card.Instance.Write创建 AI 互动卡片（卡片模式必需）
对卡片进行流式更新Card.Streaming.Write流式更新卡片内容（卡片模式必需）

步骤：

  1. 进入应用 → 权限管理
  2. 搜索「Card」相关权限
  3. 勾选上述两个权限
  4. 保存权限配置

提示：权限变更后需要重新发布应用版本才能生效。建议在开发阶段一次性开启所有可能需要的权限，避免频繁发版。

5. 启用机器人能力 ​

在 应用功能 → 机器人 中：

  1. 点击 启用 开启机器人能力
  2. 设置机器人名称（将显示在聊天列表中）
  3. 根据需要开启 支持群聊 选项

6. 消息接收模式 ​

钉钉插件使用 Stream 模式（WebSocket 长连接），类似飞书的长连接模式：

  • 无需公网地址，适合内网、本地开发等无法暴露公网端口的环境
  • 由客户端主动连接钉钉服务器，不受 NAT 和防火墙限制
  • 连接断开后会自动重连（支持指数退避重连策略）

配置步骤：

  1. 在 应用功能 → 机器人 页面
  2. 消息接收模式选择 Stream 模式
  3. 保存配置

提示：插件仅支持 Stream 模式，不支持 HTTP 回调模式。Stream 模式是最简单的部署方式，无需公网地址。

7. 发布应用 ​

  1. 在 版本管理与发布 中创建版本
  2. 填写版本号和更新说明
  3. 提交发布审核
  4. 等待组织管理员批准

提示：企业内部应用的审批通常比较快。如果您本身是管理员，可以直接在钉钉管理后台（oa.dingtalk.com）审批通过。如果长时间未批准，请联系组织管理员。

访问控制 ​

可见范围 ​

钉钉应用的可见范围决定了哪些员工可以看到并使用该应用。在钉钉开放平台的应用管理页面配置：

  1. 进入 应用发布 → 可见范围
  2. 选择可见范围：
    • 全部员工：组织内所有成员都可以使用
    • 指定部门/人员：仅选定的部门或个人可以使用

提示：在测试阶段，建议先设置为指定人员（仅包含开发团队），验证功能正常后再扩大范围。

私聊策略（dmPolicy） ​

私聊策略通过 channels.dingtalk.dmPolicy 配置：

值行为
"open"默认。 任何人都可以私聊机器人
"pairing"新用户需要通过配对码验证
"allowlist"仅 allowFrom 列表中的用户可以私聊

开放模式示例（默认）：

json5
{
  "channels": {
    "dingtalk": {
      "dmPolicy": "open"
    }
  }
}

白名单模式示例：

json5
{
  "channels": {
    "dingtalk": {
      "dmPolicy": "allowlist",
      "allowFrom": ["user_id_xxx", "user_id_yyy"]
    }
  }
}

群组策略（groupPolicy） ​

群组策略通过 channels.dingtalk.groupPolicy 配置：

值行为
"open"默认。 任何群都可以 @机器人
"allowlist"仅配置的群可以使用

@提及要求：群组中需要 @提及机器人才会响应。在钉钉群聊中，用户需要先输入 @ 然后选择机器人名称。

IP 白名单 ​

钉钉开放平台支持为应用配置服务器出口 IP 白名单，增强安全性：

  1. 进入 基础信息 → 开发管理
  2. 在 服务器出口 IP 中添加您的服务器公网 IP

提示：如果您使用 HTTP 回调模式，建议配置 IP 白名单以确保只有您的服务器能接收回调请求。Stream 模式下此配置为可选项，但仍建议配置以增强安全性。

如果服务器 IP 变更后未更新白名单，API 调用将返回权限错误。

获取用户/群组 ID ​

用户 ID（userId）：

钉钉用户标识有多种格式：

标识类型格式说明
userId数字字符串企业内用户 ID，企业内唯一
unionId字符串跨应用/跨企业的用户标识
openId字符串已弃用，建议使用 userId

获取方式：

  1. 启动网关并向机器人发送私聊消息
  2. 查看日志中的用户标识：docker compose logs -f

群组 ID（openConversationId）：

  1. 启动网关并在群组中 @提及机器人
  2. 查看日志中的 openConversationId：docker compose logs -f

注意：钉钉的群组 ID 格式为 openConversationId（如 cidXXXXXXXXXX），与飞书的 oc_xxx 格式不同。

返回 ​