| name | dingtalk-troubleshoot |
| description | 钉钉连接器问题排查。包含 dws CLI 常见错误处理、授权问题排查和连接故障诊断。
当 dws 命令执行失败、授权异常、连接中断时自动激活。
|
钉钉连接器问题排查
❓ 常见问题（FAQ）
dws 命令返回 "command not found"
现象：执行 dws 命令时提示 command not found: dws
原因：dws CLI 未安装或未加入 PATH。
解决步骤：
- 安装 dws CLI：
npm i -g dingtalk-workspace-cli
- 或使用一键安装脚本：
curl -fsSL https://github.com/open-dingtalk/dingtalk-workspace-cli/releases/latest/download/install.sh | sh
- 验证安装：
dws --version（应 >= 1.0.6）
dws 命令返回 "请先执行 dws login"
现象：执行业务命令时提示需要先登录。
原因：dws CLI 尚未完成 OAuth 授权。
解决步骤：
- 执行
dws auth login
- 终端会显示二维码，用钉钉扫码完成授权
- 授权成功后重试原命令
dws 命令返回 "token expired"
现象：命令执行失败，提示 token 已过期。
原因：OAuth access_token 已过期。
解决步骤：
- 重新执行
dws auth login 刷新授权
- 授权成功后重试原命令
dws 命令返回 "permission denied" 或 HTTP 403
现象：命令执行失败，提示权限不足。
原因：当前用户或应用缺少对应 API 的权限。
解决步骤：
- 确认操作所需的权限范围
- 联系组织管理员开通对应权限
- 权限开通后重试原命令
连接器扫码后机器人未上线
现象：完成 device-auth 扫码后，钉钉中机器人未显示在线。
可能原因：
- clientId/clientSecret 配置错误
- 钉钉应用未启用机器人能力
- 网络连接问题
排查步骤：
- 检查 openclaw 日志中是否有连接错误
- 确认钉钉开放平台中应用已启用「机器人」能力
- 确认 clientId 和 clientSecret 与开放平台一致
- 尝试重启 openclaw
🔧 错误处理流程
Recovery 闭环
当 dws 命令的 stderr 中出现 RECOVERY_EVENT_ID=<event_id> 时，说明 CLI 检测到可恢复的错误。
处理流程：
- 提取
RECOVERY_EVENT_ID 的值
- 执行
dws recovery execute --event-id <event_id> --format json 获取恢复计划
- 按恢复计划逐步执行
- 执行
dws recovery finalize --event-id <event_id> 完成闭环
详细规范见 dws-cli skill 的 recovery-guide.md。
通用错误重试
- 首次失败：加
--verbose 重试，获取详细错误信息
- 检查 stderr 是否匹配已知错误模式（未安装/未登录/过期/权限不足/Recovery）
- 匹配到已知模式：按对应 FAQ 处理
- 未匹配：将完整错误信息报告给用户，禁止自行猜测替代方案
错误码速查
各产品高频错误码及排查流程见 dws-cli skill 的 error-codes.md。
