考勤异常自动提醒与人事审批联动配置指南

当ClawBot处理企业微信考勤异常与人事审批联动时，如果消息没有触发自动响应，或者审批单迟迟没有生成，问题通常出在几个关键环节的衔接上。简单来说，可能是事件监听没注册上、审批模板没绑定对、字段映射没配全，或者是服务之间的令牌对不上号。要解决这个问题，得按顺序把下面几个环节都捋一遍。

一、确认ClawBot考勤事件监听服务已启用

首先得明白，ClawBot是靠内部的wecom适配器来接收企业微信推送的checkin_change事件的。如果这个监听服务没启动，或者对应的消息处理器没加载，那么迟到、缺卡这些异常信号就根本传不过来。

第一步，登录部署ClawBot的服务器，执行命令ps aux | grep clawdbot-wecom，看看这个进程是不是真的在运行。

第二步，去检查日志文件/var/log/clawbot/wecom.log，在里面搜一下checkin_change received这个关键词。如果能找到，说明事件成功抵达了网关；如果一片空白，那问题就出在这里。

第三步，如果确实没有日志，那就重启一下适配器试试：sudo systemctl restart clawdbot-wecom。重启后，立刻用journalctl -u clawdbot-wecom -n 30 --no-pager命令查看最近的系统日志，重点留意有没有AES解密失败或者token mismatch这类报错，这些往往是配置错误的直接表现。

二、配置考勤异常到审批单的字段映射规则

事件收到了，下一步就是处理。ClawBot需要把原始考勤消息里那些非结构化的文本（比如“张三今天迟到15分钟”），解析成结构化的数据字段（员工ID、异常类型、发生时间），然后再把这些字段填到预设的人事审批模板里去。如果这个映射规则没配好，审批单自然生成不了。

首先，打开配置文件/etc/clawbot/config.yaml，找到approval_mapping这个配置节点。

接着，在checkin_alert_fields下面，把需要的映射关系添加上去。比如：employee_name: "姓名"、exception_type: "异常类型"、occurred_at: "发生时间"。这里有个关键点：左边的键名（如employee_name）必须和审批表单JSON Schema里定义的field_id完全一致，一个字母都不能差。

最后，确认一下default_approval_template这个值。它应该是一个已经在企业微信管理后台发布并启用的审批模板ID（格式类似TEMPLATE_8a7f9c2d），而且这个模板要确保已经分配给了相关的部门。

三、启用审批流自动触发开关并校验网关令牌

配置好了映射，ClawBot默认也不会主动提交审批，这需要手动打开一个“开关”。同时，负责接收消息的wecom适配器和负责提交审批的gateway网关，它们之间通信需要用同一个令牌，如果对不上，请求就会被拒绝。

第一件事，还是在config.yaml文件里，找到auto_submit_approval_on_checkin_alert这个配置项，把它设为true。

第二件事，核对令牌。分别打开clawdbot-gateway和clawdbot-wecom的配置文件，看看gateway_token和upstream_token的值是不是一样的。通常测试环境下，它们都应该是dev-test-token。

配置修改后，不需要重启服务，执行sudo systemctl reload clawdbot-gateway && sudo systemctl reload clawdbot-wecom让配置重新加载即可生效。

四、测试端到端考勤→审批链路

前面几步都检查完了，最后一步就是做个完整的链路测试。与其等待真实的打卡行为，不如直接模拟一个标准格式的考勤异常事件发给ClawBot，这样可以快速验证从消息接收、解析、填充到最终提交的整个流程是否畅通。

首先，构造一个模拟的POST请求体，内容大致如下：

然后，使用curl命令调用ClawBot的接收接口：http://localhost:8080/api/v1/wecom/callback。注意，在请求头（Header）里一定要带上正确的令牌：X-Gateway-Token: dev-test-token。

最后，去企业微信的审批管理后台查看。如果一切正常，你应该能看到一条新的待办审批事项，申请人显示为“zhangsan”，事由字段里包含“迟到”字样，发生时间也和你请求体中发送的DateTime完全一致。看到这个，就说明整个联动流程彻底跑通了。