dingtalk-troubleshoot

name	dingtalk-troubleshoot
description	钉钉连接器问题排查。包含 dws CLI 常见错误处理、授权问题排查和连接故障诊断。 当 dws 命令执行失败、授权异常、连接中断时自动激活。

钉钉连接器问题排查

❓ 常见问题（FAQ）

dws 命令返回 "command not found"

现象：执行 dws 命令时提示 command not found: dws

原因：dws CLI 未安装或未加入 PATH。

解决步骤：

1. 安装 dws CLI：npm i -g dingtalk-workspace-cli
2. 或使用一键安装脚本：curl -fsSL https://github.com/open-dingtalk/dingtalk-workspace-cli/releases/latest/download/install.sh | sh
3. 验证安装：dws --version（应 >= 1.0.6）

dws 命令返回 "请先执行 dws login"

现象：执行业务命令时提示需要先登录。

原因：dws CLI 尚未完成 OAuth 授权。

解决步骤：

1. 执行 dws auth login
2. 终端会显示二维码，用钉钉扫码完成授权
3. 授权成功后重试原命令

dws 命令返回 "token expired"

现象：命令执行失败，提示 token 已过期。

原因：OAuth access_token 已过期。

解决步骤：

1. 重新执行 dws auth login 刷新授权
2. 授权成功后重试原命令

dws 命令返回 "permission denied" 或 HTTP 403

现象：命令执行失败，提示权限不足。

原因：当前用户或应用缺少对应 API 的权限。

解决步骤：

1. 确认操作所需的权限范围
2. 联系组织管理员开通对应权限
3. 权限开通后重试原命令

连接器扫码后机器人未上线

现象：完成 device-auth 扫码后，钉钉中机器人未显示在线。

可能原因：

• clientId/clientSecret 配置错误
• 钉钉应用未启用机器人能力
• 网络连接问题

排查步骤：

1. 检查 openclaw 日志中是否有连接错误
2. 确认钉钉开放平台中应用已启用「机器人」能力
3. 确认 clientId 和 clientSecret 与开放平台一致
4. 尝试重启 openclaw

🔧 错误处理流程

Recovery 闭环

当 dws 命令的 stderr 中出现 RECOVERY_EVENT_ID=<event_id> 时，说明 CLI 检测到可恢复的错误。

处理流程：

1. 提取 RECOVERY_EVENT_ID 的值
2. 执行 dws recovery execute --event-id <event_id> --format json 获取恢复计划
3. 按恢复计划逐步执行
4. 执行 dws recovery finalize --event-id <event_id> 完成闭环

详细规范见 dws-cli skill 的 recovery-guide.md。

通用错误重试

1. 首次失败：加 --verbose 重试，获取详细错误信息
2. 检查 stderr 是否匹配已知错误模式（未安装/未登录/过期/权限不足/Recovery）
3. 匹配到已知模式：按对应 FAQ 处理
4. 未匹配：将完整错误信息报告给用户，禁止自行猜测替代方案

错误码速查

各产品高频错误码及排查流程见 dws-cli skill 的 error-codes.md。