[Bug/Enhancement] Improve error handling for read-only filesystem on macOS local installation

[Clawiee]

Tags: bug, configuration, documentation
Quality Rating: ⭐ 8/10

---

Reporter: shuo

Description

When installing Clawith locally on macOS, creating an Agent fails with a generic Request failed error. After investigation, the root cause is that the default data directory path /data/agents is read-only on macOS, causing silent write failures.

This issue has two aspects:

1. Bug — The error message is unhelpful and does not indicate the actual cause (filesystem permission issue).
2. Enhancement — The local installation experience on macOS should handle this scenario gracefully.

Steps to Reproduce

1. Install Clawith locally on macOS
2. Start the application with default configuration
3. Attempt to create a new Agent
4. Observe a Request failed error

Expected Behavior

• The application should either:
  • Automatically detect and use a writable data directory on macOS (e.g., ~/Library/Application Support/Clawith/agents or ~/.clawith/agents)
  • Or provide a clear, actionable error message indicating that /data/agents is not writable and guide the user to set AGENT_DATA_DIR

Actual Behavior

• A generic Request failed error is shown with no indication of the root cause
• Users must manually investigate to discover the read-only filesystem issue

Suggested Improvements

1. Auto-detect writable data directory

On local/development environments (especially macOS), automatically detect that the default path is not writable and fall back to a user-writable directory.

2. Provide clear error messages

When the data directory is not writable, surface a specific error message such as:

"Cannot write to /data/agents. Please set the AGENT_DATA_DIR environment variable to a writable directory. Example: export AGENT_DATA_DIR=~/.clawith/agents"

3. Improve documentation

• Clearly document that macOS local installations require configuring AGENT_DATA_DIR
• Add this to the macOS installation guide / quick start
• Include a troubleshooting section for common local setup issues

Environment

• OS: macOS
• Installation: Local development setup

Additional Context

This is a common pain point for developers setting up Clawith locally on macOS. The combination of an unhelpful error message and an undocumented configuration requirement creates unnecessary friction in the onboarding experience.