# 钉钉Webhook配置修复指南

## 📋 问题描述

**当前问题**：所有用户消息都显示为同一个UserID（李茂林 0250340426480803），无法区分谢忠祥等其他用户。

**根本原因**：钉钉机器人Webhook配置不正确，导致UserID传递失效。

---

## 🔧 修复步骤

### 步骤1：检查钉钉后台机器人配置

#### 1.1 登录钉钉开放平台
1. 访问 https://open.dingtalk.com/
2. 使用管理员账号登录
3. 进入"应用开发" → "企业内部应用"

#### 1.2 找到对应机器人应用
1. 找到用于OpenClaw的机器人应用
2. 点击进入"应用详情"

#### 1.3 检查机器人配置
```
应用详情页 → 机器人 → 查看配置
```

**关键检查点**：
- ✅ "是否开启"：是
- ✅ "消息接收模式"：HTTP回调模式
- ✅ "回调URL"：指向OpenClaw网关地址

---

### 步骤2：配置正确的回调URL

#### 2.1 单用户模式（简单方案）

如果只需要一个机器人：

```
回调URL格式：
http://<OpenClaw服务器IP>:<端口>/webhook/ddingtalk?secret=<密钥>

示例：
http://118.126.91.196:3000/webhook/ddingtalk?secret=your-secret-key
```

#### 2.2 多用户模式（推荐方案）

为不同用户配置不同机器人：

| 用户 | 机器人名称 | 回调URL |
|------|-----------|---------|
| 李茂林 | OpenClaw-CEO | `.../webhook/ddingtalk?user=limaolin&secret=xxx` |
| 谢忠祥 | OpenClaw-RD | `.../webhook/ddingtalk?user=xiezhongxiang&secret=xxx` |

**操作步骤**：
1. 为每个用户创建单独的机器人应用
2. 每个机器人独立的回调URL
3. OpenClaw根据URL参数识别用户

---

### 步骤3：配置OpenClaw网关

#### 3.1 编辑OpenClaw配置文件

```bash
# 找到配置文件
vim ~/.openclaw/config.yaml

# 或
vim /etc/openclaw/config.yaml
```

#### 3.2 添加钉钉Webhook配置

```yaml
# 钉钉Webhook配置
webhooks:
  ddingtalk:
    # 主配置
    enabled: true
    port: 3000
    path: /webhook/ddingtalk
    
    # 用户映射（关键！）
    userMapping:
      # 方式1：通过URL参数映射
      paramMapping:
        limaolin: "0250340426480803"
        xiezhongxiang: "014513372735266855"
        wangzhongqiang: "02466842012229318510"
      
      # 方式2：通过机器人AppID映射
      appIdMapping:
        "dingxxxxxxxxxxxx1": "0250340426480803"  # 李茂林的机器人
        "dingxxxxxxxxxxxx2": "014513372735266855"  # 谢忠祥的机器人
    
    # 密钥验证
    secrets:
      - "your-secret-key-1"
      - "your-secret-key-2"
```

#### 3.3 重启OpenClaw网关

```bash
# 重启服务
openclaw gateway restart

# 或
systemctl restart openclaw

# 检查状态
openclaw gateway status
```

---

### 步骤4：验证UserID传递

#### 4.1 测试消息发送

让谢忠祥发送一条测试消息：
```
【测试】我是谢忠祥
```

#### 4.2 检查OpenClaw日志

```bash
# 查看日志
tail -f /var/log/openclay/webhook.log

# 或
tail -f ~/.openclaw/logs/webhook.log
```

**正确日志应显示**：
```json
{
  "timestamp": "2026-03-03T16:00:00Z",
  "channel": "ddingtalk",
  "userId": "014513372735266855",  // 谢忠祥的ID
  "userName": "谢忠祥",
  "message": "【测试】我是谢忠祥"
}
```

---

## 🔍 常见问题排查

### 问题1：所有消息都显示同一个UserID

**原因**：钉钉没有正确传递senderStaffId

**解决**：
1. 检查机器人是否有"读取通讯录"权限
2. 确保应用已发布（不是开发版本）
3. 检查回调URL是否正确接收POST数据

### 问题2：UserID为空或不正确

**原因**：钉钉推送格式变更

**解决**：
1. 更新OpenClaw到最新版本
2. 检查钉钉开放平台文档
3. 手动解析钉钉推送的JSON数据

### 问题3：部分用户消息收不到

**原因**：Webhook有频率限制

**解决**：
1. 钉钉免费版：20次/秒
2. 钉钉专业版：100次/秒
3. 超出限制会丢弃消息

---

## ✅ 验证清单

配置完成后检查：

- [ ] 李茂林发消息 → 显示UserID: 0250340426480803
- [ ] 谢忠祥发消息 → 显示UserID: 014513372735266855
- [ ] 其他用户发消息 → 显示对应UserID
- [ ] AI能正确识别不同用户身份
- [ ] 权限控制正常工作

---

## 📞 技术支持

如仍有问题：
1. 查看钉钉开放平台文档：https://open.dingtalk.com/document/
2. 检查OpenClaw日志定位问题
3. 联系OpenClaw技术支持

---

**重要提示**：
- 修改配置后必须重启OpenClaw网关
- 建议先在测试环境验证
- 备份原有配置后再修改