| name | dingtalk-attendance |
| description | 当用户提到'考勤'、'打卡'、'迟到'、'早退'、'补卡'、'请假'、'出勤'、'缺勤'、'考勤报表'、'考勤异常'时使用此技能。查询钉钉考勤打卡记录、考勤结果、排班信息，识别异常并生成汇总报告。 |
| version | 0.1.0 |
| metadata | {"openclaw":{"emoji":"⏰","requires":{"env":["DINGTALK_APP_KEY","DINGTALK_APP_SECRET"],"bins":["curl","jq"]},"primaryEnv":"DINGTALK_APP_KEY"}} |
钉钉考勤操作技能
通过钉钉开放平台考勤 API，查询打卡记录、考勤结果、排班数据，并识别考勤异常。
前置条件
应用需申请权限：查询企业考勤数据权限。先获取 access_token：
ACCESS_TOKEN=$(curl -s "https://oapi.dingtalk.com/gettoken?appkey=${DINGTALK_APP_KEY}&appsecret=${DINGTALK_APP_SECRET}" | jq -r '.access_token')
核心操作
1. 获取考勤结果（最常用）
查询员工某段日期的考勤汇总结果（正常/迟到/早退/缺卡/请假等）：
curl -s -X POST "https://oapi.dingtalk.com/attendance/listRecord?access_token=${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"userIds": ["<userId1>", "<userId2>"],
"checkDateFrom": "2026-03-01T00:00:00+08:00",
"checkDateTo": "2026-03-04T23:59:59+08:00",
"isI18n": false
}' | jq '.recordresult'
返回值关键字段：
checkType: OnDuty(上班) / OffDuty(下班)timeResult: Normal(正常) / Early(早退) / Late(迟到) / SeriousLate(严重迟到) / Absenteeism(旷工) / NotSigned(未打卡)userCheckTime: 实际打卡时间（毫秒时间戳）planCheckTime: 应打卡时间
2. 获取打卡详情
查询原始打卡流水（包括打卡地点、设备等）：
curl -s -X POST "https://oapi.dingtalk.com/attendance/list?access_token=${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"workDateFrom": "2026-03-01T00:00:00+08:00",
"workDateTo": "2026-03-04T23:59:59+08:00",
"userIdList": ["<userId1>"],
"offset": 0,
"limit": 50
}' | jq '.recordresult'
3. 获取排班信息
查询员工的排班计划（班次、上下班时间）：
curl -s -X POST "https://oapi.dingtalk.com/topapi/attendance/listschedule?access_token=${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"workDate": "2026-03-04",
"offset": 0,
"size": 200
}' | jq '.result.schedules'
4. 获取考勤组列表
curl -s -X POST "https://oapi.dingtalk.com/topapi/attendance/getsimplegroups?access_token=${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"offset": 0,
"size": 10
}' | jq '.result.groups'
5. 获取部门用户列表（辅助——获取 userId）
curl -s -X POST "https://oapi.dingtalk.com/topapi/user/listsimple?access_token=${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"dept_id": 1,
"cursor": 0,
"size": 100
}' | jq '.result.list'
dept_id=1 为根部门。用 .result.list[].userid 获取 userId 列表。
典型工作流
每日考勤异常检测：
- 获取根部门下所有 userId
- 调用
listRecord 查询今日考勤结果
- 筛选
timeResult 不为 Normal 的记录
- 按异常类型分组（迟到/早退/未打卡）
- 生成汇总报告，推送到 HR 群
- 对未打卡员工发送工作通知提醒补卡
注意事项
- 单次查询
userIds 最多 50 人，超出需分批
- 日期格式必须含时区：
2026-03-04T00:00:00+08:00
- 考勤数据有延迟，建议查询前一天及更早的数据以确保完整
- 钉钉考勤 API 调用频率有限制，对大型企业（500+人）需分批查询并控制频率
