| name | dingtalk-approval |
| description | 当用户要求'发起审批'、'查看审批'、'催办审批'、'请假'、'报销'、'采购申请'，或提到钉钉OA审批相关操作时使用此技能。管理钉钉审批流程：发起审批实例、查询审批状态、获取审批列表、催办超时审批。 |
| version | 0.1.0 |
| metadata | {"openclaw":{"emoji":"📋","requires":{"env":["DINGTALK_APP_KEY","DINGTALK_APP_SECRET"],"bins":["curl","jq"]},"primaryEnv":"DINGTALK_APP_KEY"}} |
钉钉审批流操作技能
通过钉钉开放平台 OA 审批 API，实现审批实例的发起、查询、催办等操作。
前置条件
- 需要在钉钉开放平台创建企业内部应用
- 应用需申请以下权限：审批实例读写权限（全部 5 个审批相关权限）
- 环境变量
DINGTALK_APP_KEY 和 DINGTALK_APP_SECRET 已配置
获取 Access Token
所有 API 调用前，先获取 access_token（有效期 7200 秒，可缓存）：
ACCESS_TOKEN=$(curl -s "https://oapi.dingtalk.com/gettoken?appkey=${DINGTALK_APP_KEY}&appsecret=${DINGTALK_APP_SECRET}" | jq -r '.access_token')
核心操作
1. 获取审批模板列表
查询企业已有的审批模板，获取 process_code（发起审批必需）：
curl -s -X POST "https://oapi.dingtalk.com/topapi/process/listbyuserid?access_token=${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"userid": "<发起人的userId>",
"offset": 0,
"size": 100
}' | jq '.result.process_list'
2. 发起审批实例
用 process_code 和表单数据发起一个审批：
curl -s -X POST "https://oapi.dingtalk.com/topapi/processinstance/create?access_token=${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"process_code": "<模板的process_code>",
"originator_user_id": "<发起人userId>",
"dept_id": <发起人部门ID>,
"form_component_values": [
{
"name": "请假类型",
"value": "事假"
},
{
"name": "开始时间",
"value": "2026-03-04"
},
{
"name": "结束时间",
"value": "2026-03-05"
},
{
"name": "请假事由",
"value": "家中有事需处理"
}
]
}'
返回值包含 process_instance_id，需保存用于后续查询。
表单字段类型说明：
- 单行输入框 / 多行输入框：
"value": "文本内容"
- 数字：
"value": "12000"
- 日期：
"value": "2026-03-04"
- 日期区间：
"value": "[\"2026-03-04\", \"2026-03-05\"]"
- 单选框：
"value": "选项A"
- 多选框：
"value": "[\"选项A\", \"选项B\"]"
- 明细（子表）：
"value": "[{\"name\":\"品名\",\"value\":\"电焊条\"},{\"name\":\"数量\",\"value\":\"500\"}]"
3. 查询单个审批实例详情
curl -s -X POST "https://oapi.dingtalk.com/topapi/processinstance/get?access_token=${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"process_instance_id": "<审批实例ID>"
}' | jq '.process_instance'
返回值关键字段：
status: NEW(新创建) / RUNNING(审批中) / TERMINATED(被撤销) / COMPLETED(完成)result: agree(同意) / refuse(拒绝)operation_records: 操作记录数组tasks: 审批任务数组（当前待审批人）
4. 批量获取审批实例 ID 列表
curl -s -X POST "https://oapi.dingtalk.com/topapi/processinstance/listids?access_token=${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"process_code": "<模板process_code>",
"start_time": 1709510400000,
"end_time": 1709596800000,
"size": 20,
"cursor": 0
}' | jq '.result.list'
时间戳为毫秒级 Unix 时间。可按 userid_list 过滤特定发起人。
5. 获取用户待审批数量
curl -s -X POST "https://oapi.dingtalk.com/topapi/process/gettodonum?access_token=${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"userid": "<用户userId>"
}' | jq '.result.count'
6. 发送工作通知（催办）
向指定用户推送一条工作通知消息（出现在钉钉"工作通知"里）：
curl -s -X POST "https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2?access_token=${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"agent_id": <应用agentId>,
"userid_list": "<userId1>,<userId2>",
"msg": {
"msgtype": "text",
"text": {
"content": "您有一条审批单已超过24小时未处理，请尽快审批。审批单号：XXX"
}
}
}'
典型工作流
查询超时未处理审批并催办：
- 用
listids 获取近 N 天的审批实例 ID
- 逐个用
get 查询详情，筛选 status=RUNNING 且创建时间超过阈值的
- 从
tasks 中提取当前待审批人 userId
- 用工作通知 API 向待审批人发送催办消息
- 汇总结果生成报告
自然语言发起审批：
- 用户说"帮我发起请假，3月10日到3月12日，事假，家中有事"
- 解析意图，识别模板类型（请假）
- 用
listbyuserid 获取请假模板的 process_code
- 构造 form_component_values
- 调用
create 发起审批
- 返回审批实例 ID 给用户
注意事项
- access_token 有效期 7200 秒，不要每次调用都重新获取，应缓存复用
- 钉钉 API 有调用频率限制，触发限流会返回错误码，需实现退避重试
process_code 在钉钉管理后台创建审批模板时，可从浏览器 URL 中的 process_code 参数获取- 发起审批需要知道发起人的
userId 和 dept_id，可通过通讯录 API 获取
- 审批状态变更可通过 Stream 事件订阅实时获取（事件类型：
bpms_instance_change）
Additional Resources
