💬 OpenClaw 钉钉集成

    <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"

        <p><strong>方式二：配置文件</strong></p>
        <pre><code>openclaw config --section channels

选择 DingTalk 并按提示操作

        <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"
}]
}

    <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

        <p><strong>Step 2: 启用插件</strong></p>
        <pre><code># 编辑 ~/.openclaw/openclaw.json

{
"plugins": {
"enabled": true,
"allow": ["dingtalk"]
}
}

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

openclaw configure --section channels

或手动编辑配置文件

openclaw config --section channels

        <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>