dingtalk-troubleshoot

DingTalk Connector Troubleshooting

❓ Frequently Asked Questions (FAQ)

dws command returns "command not found"

Symptom: When executing the dws command, it prompts command not found: dws

Cause: The dws CLI is not installed or not added to PATH.

Resolution steps：

1. Install the dws CLI:npm i -g dingtalk-workspace-cli
2. Or use the one-click install script:curl -fsSL https://github.com/open-dingtalk/dingtalk-workspace-cli/releases/latest/download/install.sh | sh
3. Verify the installation:dws --version(should be >= 1.0.6)

dws command returns "please run dws login first"

Symptom: When executing a business command, it prompts that you need to log in first.

Cause: The dws CLI has not yet completed OAuth authorization.

Resolution steps：

1. Execute dws auth login
2. The terminal will display a QR code; scan it with DingTalk to complete authorization
3. After successful authorization, retry the original command

dws command returns "token expired"

Symptom: The command fails, prompting that the token has expired.

Cause: The OAuth access_token has expired.

Resolution steps：

1. Re-execute dws auth login to refresh authorization
2. After successful authorization, retry the original command

dws command returns "permission denied" or HTTP 403

Symptom: The command fails, prompting insufficient permissions.

Cause: The current user or application lacks permission for the corresponding API.

Resolution steps：

1. Confirm the permission scope required for the operation
2. Contact the organization administrator to enable the corresponding permission
3. After the permission is enabled, retry the original command

The bot does not come online after the connector QR code scan

Symptom: After completing the device-auth QR code scan, the bot does not show as online in DingTalk.

Possible causes：

• clientId/clientSecret configuration error
• The DingTalk application has not enabled the bot capability
• Network connection issue

Troubleshooting steps：

1. Check whether there are connection errors in the openclaw logs
2. Confirm that the "Bot" capability has been enabled for the application in the DingTalk Open Platform
3. Confirm that clientId and clientSecret match those on the Open Platform
4. Try restarting openclaw

🔧 Error Handling Process

Recovery Loop

When RECOVERY_EVENT_ID=<event_id> appears in the stderr of a dws command, it indicates that the CLI has detected a recoverable error.

Handling process：

1. Extract RECOVERY_EVENT_ID value
2. Execute dws recovery execute --event-id <event_id> --format json to get the recovery plan
3. Execute step by step according to the recovery plan
4. Execute dws recovery finalize --event-id <event_id> to complete the loop

For detailed specifications, see the dws-cli skill's recovery-guide.md。

General Error Retry

1. First failure: add --verbose retry to obtain detailed error information
2. Check whether stderr matches a known error pattern (not installed/not logged in/expired/insufficient permissions/Recovery)
3. Matched a known pattern: handle according to the corresponding FAQ
4. Not matched: report the complete error information to the user; do not guess alternative solutions on your own

Error Code Quick Reference

For high-frequency error codes and troubleshooting procedures for each product, see the dws-cli skill's error-codes.md。