email-diagnose（电子邮件诊断）

Email Channel Diagnostics

Stage 1: Collect data

Run the diagnostic script against OpenClaw logs:

node scripts/diagnose.mjs --date YYYY-MM-DD [--account id] [--verbose] [--logdir path]

Parameters:

• --date — Log date (default: today). Format: YYYY-MM-DD
• --account — Filter to a specific account ID (e.g., default, worker)
• --verbose — Include full timeline in output
• --logdir — Log directory (default: /tmp/openclaw)

Stage 2: Analyze report

Read the JSON output and analyze in this priority order:

1. errors[] — Check each error entry. Match tag and message against the patterns in references/troubleshooting.md.
2. byTag — High error/warn counts identify the broken subsystem: Common (both transports): IMAP transport: WS transport:

- EMAIL-ACCOUNT → config issues - EMAIL-MONITOR → monitoring/receiving issues - EMAIL-CHANNEL → routing/dispatch issues - EMAIL-A2A → agent filtering issues - EMAIL-PARSER → attachment issues - EMAIL-IMAP → connection/auth issues - EMAIL-SMTP → sending issues - UID-STORE → state tracking issues - EMAIL-WS → WebSocket connection issues - EMAIL-IM → IM protocol issues - EMAIL-TOKEN → token auth issues - EMAIL-SDK → SDK fetch/send issues

1. warns[] — May indicate developing problems (reconnects, whitelist rejections)
2. perf — Performance anomalies: IMAP transport: WS transport: Both transports:

- smtpFailCount > 0 → SMTP sending broken - imapReconnectCount > 5 → unstable IMAP connection - wsReconnectCount > 5 → unstable WebSocket connection - tokenFailCount > 0 → token auth broken - sdkFetchFailCount > 0 → SDK fetch broken - imAuthFailCount > 0 → IM authentication broken - emailsRejected / emailsProcessed > 50% → whitelist too strict

1. timeline (verbose only) — Trace the full event flow for a specific email

Match the issue to a troubleshooting pattern. Read references/troubleshooting.md for the matching pattern number.

Stage 3: Present findings and guide fix

Present the diagnosis to the user:

1. Summarize what's wrong in plain language (not log tags)
2. Identify which troubleshooting pattern applies
3. Walk through fix steps from references/troubleshooting.md
4. For common fixes, offer to execute (with user confirmation):

- Config field missing → show exact JSON path and field to add - UID store reset → rm ~/.openclaw/email/uid-store/<accountId>.json - Whitelist adjustment → show the allowFrom config to modify - Restart gateway → systemctl --user restart openclaw-gateway

Stage 4: Escalate if unresolved

If the user confirms the issue is not resolved after fix attempts:

1. Ask: "Would you like to package the diagnostic logs and send them to claw.feedback@claw.163.com for the support team?"
2. Warn: "The log package may contain email addresses and account IDs. Review before sending."
3. If user agrees — try mail-cli first: # Package logs TIMESTAMP=$(date +%Y%m%d-%H%M%S) tar czf /tmp/email-diag-${TIMESTAMP}.tar.gz \ /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log # Send via mail-cli (use absolute paths for --attach) mail-cli compose send \ --to "claw.feedback@claw.163.com" \ --subject "[Email-Diag] <brief issue summary>" \ --body "<diagnosis summary and steps tried>" \ --attach /tmp/email-diag-${TIMESTAMP}.tar.gz
4. If mail-cli not available or send fails:

- Tell user the tar.gz path: /tmp/email-diag-<timestamp>.tar.gz - Ask them to manually email it to claw.feedback@claw.163.com - Include the diagnosis summary in the email body

Quick reference: log tags