# OpenClaw 钉钉集成：dingtalk vs dingtalk-setup 详解

> 作者: Elaine
> 日期: 2026-03-17
> 标签: OpenClaw, 钉钉

---

<h1>💬 OpenClaw 钉钉集成</h1>
        <p class="subtitle">dingtalk vs dingtalk-setup 区别与使用指南</p>

        <div class="section">
            <h3>引言</h3>
            <p>在使用 OpenClaw 连接钉钉时，你可能会看到两个相关的 Skill：<code>dingtalk</code> 和 <code>dingtalk-setup</code>。它们分别扮演什么角色？有什么区别？本文将为你详细解答。</p>
        </div>

        <h2>1. 两个 Skill 的区别</h2>

        <div class="section">
            <table class="compare-table">
                <tr>
                    <th>特性</th>
                    <th>dingtalk</th>
                    <th>dingtalk-setup</th>
                </tr>
                <tr>
                    <td><strong>性质</strong></td>
                    <td>OpenClaw 插件 (Channel Plugin)</td>
                    <td>配置引导 Skill</td>
                </tr>
                <tr>
                    <td><strong>作用</strong></td>
                    <td>实际处理钉钉消息的发送/接收</td>
                    <td>指导用户完成钉钉渠道的配置</td>
                </tr>
                <tr>
                    <td><strong>功能</strong></td>
                    <td>消息收发、用户管理、群聊支持</td>
                    <td>安装插件、配置参数、排查问题</td>
                </tr>
                <tr>
                    <td><strong>是否必需</strong></td>
                    <td>✅ 必需（核心组件）</td>
                    <td>❌ 可选（仅首次配置时使用）</td>
                </tr>
                <tr>
                    <td><strong>使用频率</strong></td>
                    <td>持续运行</td>
                    <td>一次性</td>
                </tr>
            </table>
        </div>

        <h2>2. dingtalk 插件详解</h2>

        <div class="section">
            <h3>2.1 是什么？</h3>
            <p><code>dingtalk</code> 是 OpenClaw 的钉钉通道插件，负责：</p>
            <ul>
                <li>✅ 接收钉钉消息</li>
                <li>✅ 发送钉钉消息</li>
                <li>✅ 支持企业内部应用和 Webhook 机器人</li>
                <li>✅ 私聊 (DM) 和群聊管理</li>
                <li>✅ 用户白名单支持</li>
            </ul>
        </div>

        <div class="section">
            <h3>2.2 配置方式</h3>
            
            <p><strong>方式一：环境变量</strong></p>
            <pre><code>export DINGTALK_CLIENT_ID="your-app-key"
export DINGTALK_CLIENT_SECRET="your-app-secret"</code></pre>

            <p><strong>方式二：配置文件</strong></p>
            <pre><code>openclaw config --section channels
# 选择 DingTalk 并按提示操作</code></pre>

            <p><strong>方式三：Webhook 机器人（群聊）</strong></p>
            <pre><code>{
  "channels": [{
    "id": "dingtalk",
    "plugin": "dingtalk",
    "enabled": true,
    "webhookUrl": "https://oapi.dingtalk.com/robot/send?access_token=xxxxx",
    "webhookSecret": "SECxxxxx"
  }]
}</code></pre>
        </div>

        <div class="section">
            <h3>2.3 完整配置参数</h3>
            <table>
                <tr><th>参数</th><th>必需</th><th>说明</th></tr>
                <tr><td>clientId</td><td>✅</td><td>钉钉 App Key</td></tr>
                <tr><td>clientSecret</td><td>✅</td><td>钉钉 App Secret</td></tr>
                <tr><td>robotCode</td><td>❌</td><td>机器人代码</td></tr>
                <tr><td>corpId</td><td>❌</td><td>企业 ID</td></tr>
                <tr><td>agentId</td><td>❌</td><td>应用 Agent ID</td></tr>
                <tr><td>dm</td><td>❌</td><td>私聊策略：open / allowlist</td></tr>
                <tr><td>group</td><td>❌</td><td>群聊策略：open / allowlist</td></tr>
            </table>
        </div>

        <h2>3. dingtalk-setup 详解</h2>

        <div class="section">
            <h3>3.1 是什么？</h3>
            <p><code>dingtalk-setup</code> 是一个配置引导 Skill，专门帮助用户：</p>
            <ul>
                <li>🤖 安装 dingtalk 插件</li>
                <li>⚙️ 配置钉钉渠道参数</li>
                <li>🔧 排查钉钉消息问题</li>
                <li>📝 提供自动化部署脚本</li>
            </ul>
        </div>

        <div class="section">
            <h3>3.2 使用场景</h3>
            <p><strong>✅ 应该使用：</strong></p>
            <ul>
                <li>用户说"对接钉钉"、"配置钉钉机器人"</li>
                <li>钉钉消息没有响应，需要排查</li>
                <li>需要安装钉钉插件</li>
            </ul>

            <p><strong>❌ 不应该使用：</strong></p>
            <ul>
                <li>飞书/Lark 配置 → 使用 <code>feishu</code> skill</li>
                <li>企业微信 → 使用 <code>wecom</code> skill</li>
                <li>Telegram/Discord → 使用对应的 channel skill</li>
            </ul>
        </div>

        <div class="section">
            <h3>3.3 配置步骤</h3>
            
            <p><strong>Step 1: 安装插件</strong></p>
            <pre><code># 国内网络（推荐）
$env:NPM_CONFIG_REGISTRY="https://registry.npmmirror.com"
openclaw plugins install @soimy/dingtalk

# 国际网络
openclaw plugins install @soimy/dingtalk</code></pre>

            <p><strong>Step 2: 启用插件</strong></p>
            <pre><code># 编辑 ~/.openclaw/openclaw.json
{
  "plugins": {
    "enabled": true,
    "allow": ["dingtalk"]
  }
}</code></pre>

            <p><strong>Step 3: 配置渠道</strong></p>
            <pre><code># 交互式配置（推荐）
openclaw configure --section channels

# 或手动编辑配置文件
openclaw config --section channels</code></pre>

            <p><strong>Step 4: 重启 Gateway</strong></p>
            <pre><code>openclaw gateway restart</code></pre>
        </div>

        <h2>4. 常见问题排查</h2>

        <div class="section">
            <div class="warning">
                <div class="warning-title">🔧 排查清单</div>
                <ul>
                    <li>✅ Gateway 运行中 → <code>openclaw gateway status</code></li>
                    <li>✅ 插件在白名单 → 检查 <code>plugins.allow</code> 包含 <code>"dingtalk"</code></li>
                    <li>✅ 渠道已启用 → 检查 <code>channels[].enabled</code> 为 <code>true</code></li>
                    <li>✅ 凭证正确 → 在钉钉开放平台验证 Client ID/Secret</li>
                    <li>✅ 重启 Gateway → <code>openclaw gateway restart</code></li>
                </ul>
            </div>

            <h3>常见错误</h3>
            <table>
                <tr><th>错误</th><th>解决方案</th></tr>
                <tr><td>Plugin not found</td><td>确认插件已安装，检查目录存在</td></tr>
                <tr><td>Connection failed</td><td>验证凭证，检查网络连接</td></tr>
                <tr><td>Plugin not loaded</td><td>添加到 plugins.allow，重启 Gateway</td></tr>
                <tr><td>invalid timestamp</td><td>同步系统时间</td></tr>
                <tr><td>app not authorized</td><td>检查钉钉开放平台应用权限</td></tr>
            </table>
        </div>

        <h2>5. 总结</h2>

        <div class="section">
            <p>简单理解两者的关系：</p>
            <ul>
                <li><code>dingtalk</code> = <strong>司机</strong>（负责实际开车）</li>
                <li><code>dingtalk-setup</code> = <strong>教练</strong>（教你如何开车，教会就走）</li>
            </ul>

            <p style="margin-top: 20px;"><strong>推荐流程：</strong></p>
            <ol>
                <li>首次配置：使用 <code>dingtalk-setup</code> 完成安装和配置</li>
                <li>日常使用：<code>dingtalk</code> 插件自动处理消息</li>
                <li>遇到问题：再次参考 <code>dingtalk-setup</code> 排查</li>
            </ol>
        </div>