认证失败时应优先启用自动刷新并验证Token有效期，其次重置授权重建凭证链，再检查企业微信IP白名单配置，最后可改用应用级App Access Token直连。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在通过微信调用OpenClaw API时遭遇认证失败，常见表现为返回错误码{"code":99991663,"msg":"token_expired"}或HTTP 401响应，则极可能源于微信Access Token失效或OpenClaw本地凭证未同步刷新。以下是针对该问题的多种可执行修复路径：
一、强制触发OAuth Token自动刷新流程
OpenClaw内置Credential Monitoring模块支持基于Refresh Token的自动续期，但需确保配置已启用且Refresh Token有效。该机制依赖于飞书OAuth协议兼容逻辑，亦适用于微信生态中采用相同标准的授权链路。
1、确认当前配置中已启用自动刷新开关：
执行命令 openclaw config get auth.refresh_enabled，预期输出为 true。
2、若返回 false，立即启用：openclaw config set auth.refresh_enabled true。
3、手动触发一次刷新验证：openclaw auth refresh --provider wecom（注意provider参数必须指定为wecom）。
4、检查刷新后生成的新Token有效期：openclaw auth info --provider wecom | grep expires_at，确认时间戳距当前不足2小时。
二、重置微信应用授权并重建凭证链
当Refresh Token本身已过期或被微信后台主动吊销时，自动刷新将失败。此时必须中断旧授权关系，引导用户重新完成OAuth 2.0授权码流程，以获取全新且有效的Access Token与Refresh Token组合。
1、调用微信开放平台API撤销当前授权：
向 https://qyapi.weixin.qq.com/cgi-bin/service/terminate?access_token=YOUR_APP_ACCESS_TOKEN 发送POST请求，其中YOUR_APP_ACCESS_TOKEN为应用级Token。
2、清除OpenClaw本地存储的微信凭证缓存：
执行 rm -f ~/.openclaw/credentials/wecom.json（Linux/macOS）或 del %USERPROFILE%\.openclaw\credentials\wecom.json（Windows）。
3、启动本地网关并访问授权回调地址：
打开浏览器，访问 http://localhost:18789/auth/wecom/start，按提示完成企业微信扫码授权。
4、授权成功后，OpenClaw将自动写入新凭证至磁盘，并在控制台打印 [INFO] Credentials for wecom saved successfully。
三、校验并修正企业微信可信IP白名单配置
即使Token有效，若OpenClaw网关服务器的出口IP未被列入企业微信应用的“可信IP列表”，微信服务器将在回调阶段拒绝接收请求，导致后续所有凭证操作静默失败，日志中仅显示空响应或连接超时。
1、获取当前网关实际出口IP：
执行 curl -s https://api64.ipify.org 或访问 https://api64.ipify.org 获取IPv4地址。
2、登录企业微信管理后台 → 应用管理 → 自建应用 → IP白名单设置页面。
3、将上一步获取的IP地址填入白名单字段，**必须包含子网掩码**，例如：203.0.113.42/32（单IP）或 203.0.113.0/24（网段）。
4、保存配置后，等待企业微信后台约2分钟同步生效，再执行一次 openclaw auth test --provider wecom 验证连通性。
四、绕过Token机制直连应用级API密钥验证
对于仅需调用企业微信管理类接口（如创建部门、获取成员列表）的场景，可跳过用户级OAuth流程，改用应用Secret生成的App Access Token。该Token由OpenClaw网关在内存中缓存并自动轮转，不依赖外部刷新逻辑。
1、从企业微信后台复制“应用Secret”值，确保其长度为40位十六进制字符串。
2、在OpenClaw配置中写入该密钥：openclaw config set wecom.app_secret "your_40_char_app_secret"。
3、强制生成新的App Access Token：openclaw auth generate-app-token --provider wecom。
4、验证Token是否可用：
执行 curl -X GET "https://qyapi.weixin.qq.com/cgi-bin/user/getuserinfo?access_token=$(openclaw auth get-app-token --provider wecom)&code=testcode"，应返回合法JSON响应而非errcode:40014。
