Improve error handling and diagnostic messages in copaw-worker MinIO sync

[hobostay]

Summary

• Enhanced error messages in copaw-worker's MinIO sync module
• Added endpoint validation to detect common port configuration mistakes
• Improved mc binary not found error with installation instructions
• Added detailed error handling for connection and authentication failures
• Added JSON parsing error handling for openclaw.json

Problem

Issue #200 reports that copaw-worker command fails with unclear error message when mc alias set fails:

Failed to pull config: Command '['/home/caifx/.local/bin/mc', 'alias', 'set', 'hiclaw',
'http://fs-local.hiclaw.io:18080', 'browser-agent', 'fa50746fe92f3a5a2423423f0e3ced42aa7f7be32c30c24b']' returned
non-zero exit status 1.

The error doesn't provide enough context for users to diagnose the problem.

Root Cause Analysis

The most likely cause of the reported issue is using the wrong endpoint:

• User passed --fs http://fs-local.hiclaw.io:18080
• Port 18080 is the Higress Console port, not MinIO
• MinIO typically runs on port 9000 (HTTP) or 9001 (HTTPS)

Changes

1. Endpoint Validation

Added warning when detecting Higress Console ports:

if ":18080" in url or ":18001" in url:
    logger.warning(
        "WARNING: The MinIO endpoint appears to be using a Higress Console port (%s).\n"
        "MinIO typically runs on port 9000 (or 9001 for HTTPS).\n"
        "If you're trying to connect to HiClaw's MinIO, check your --fs parameter.",
        url
    )

2. Improved Error Messages

For mc alias set failures, now provides:

• Connection refused: Lists 4 possible causes with troubleshooting steps
• Authentication failures: Lists 3 things to check
• Full mc stderr output for debugging

3. Better openclaw.json Error

When config is not found:

• Shows expected MinIO path
• Suggests verification command using mc ls
• Mentions Manager needs to create config first

4. Installation Instructions

When mc binary is not found, provides platform-specific installation instructions.

Testing

The changes are backward compatible - only error messages are improved. Users who had correct configurations will see no difference.

Example Output

Before:

Failed to pull config: Command 'mc alias set hiclaw ...' returned non-zero exit status 1.

After:

WARNING: The MinIO endpoint appears to be using a Higress Console port (http://fs-local.hiclaw.io:18080).
MinIO typically runs on port 9000 (or 9001 for HTTPS).
If you're trying to connect to HiClaw's MinIO, check your --fs parameter.

Failed to configure MinIO connection.
  Endpoint: http://fs-local.hiclaw.io:18080
  Access Key: browser-***
  
Connection refused. Possible causes:
  1. MinIO server is not running
  2. Wrong host/port - MinIO default is port 9000, not 18080
  3. Firewall blocking the connection
  4. Using wrong endpoint URL (e.g., Higress Console instead of MinIO)

Related to #200

🤖 Generated with Claude Code