FAQ

Installation & Startup

Q: The app opens to a blank screen or fails to load. What should I check?

The Go sidecar engine may not have started correctly. Check the following:

1. Inspect the Logs page for startup errors
2. Confirm that port 16060 is not already in use
3. Restart the app and allow up to 30 seconds for the sidecar to come up automatically

Q: macOS says the app cannot be opened because the developer cannot be verified.

Right-click the app, choose Open, and confirm in the dialog. You can also run:

xattr -cr /Applications/HexClaw.app

Q: How do I launch HexClaw at login?

Go to Settings → General → Launch at Login and enable it. On macOS this is implemented through LaunchAgent.

Models & Chat

Q: My API request returns a 401 or 403 error.

The API key is usually invalid, expired, or missing quota. Go to Settings → Model Providers, verify the key, and confirm the account is funded.

Q: How do I use local models with no network dependency?

Install Ollama, then add it as a provider in HexClaw:

• Base URL: http://localhost:11434/v1
• API Key: leave empty
• Model: add the downloaded model names manually, such as llama3.1 or qwen2.5

Q: Streaming output seems stuck.

This is often a network timeout. Press Esc to stop generation, then resend the message.

Data & Privacy

Q: Where is my data stored?

All data is stored locally:

• Sessions and messages: SQLite database (hexclaw.db)
• Settings: Tauri Store, usually as local JSON files
• API keys: the operating system's secure key store
• Data directory: visible in Settings → General → Data Directory

Q: Does HexClaw send my data to third-party servers?

No relay service is involved. HexClaw only talks to the AI API endpoints you configure. If you use Ollama, the entire flow can stay offline.

Workflows & Agents

Q: A workflow run failed. What should I inspect?

Open the failed node and read the error details. Common causes include an agent with no configured model, disconnected MCP tools, or token limits.

Q: How many agents should I include in a multi-agent meeting?

There is no hard cap, but 2 to 5 agents is the practical range. More agents usually mean longer discussions and higher token usage.

MCP & Tools

Q: My MCP server connection fails.

1. Confirm the server process is actually running
2. Check that the transport type matches the server implementation: stdio, sse, or streamable_http
3. Inspect the Logs page for the full error message

Deep Research

Deep research mode is stuck on the "searching" stage. What should I do?

Confirm the agent has access to a web search tool (the web_search Skill must be enabled). If the backend has no search Skill configured, research mode will fall back to a regular agent response.

The research report quality is not satisfactory.

Try the following:

• Use a more capable model (e.g. Claude Sonnet 4 or GPT-4o)
• Provide a more specific research topic and scope
• Specify the desired output format in your prompt (e.g. "generate a Markdown report with citations")

IM Channels

I configured Feishu / DingTalk / WeCom but receive no messages.

1. Make sure you restart the Engine after saving the configuration
2. Verify the App Secret / Token (note: test and production credentials may differ)
3. Confirm the bot has been added to the target group or has message-receiving permissions enabled
4. Check the Logs page for connection errors

Skill Marketplace

A skill installed from ClawHub does not take effect.

ClawHub is currently in mock mode (local preview only). The install action does not actually download skill files. Once the full release ships, it will connect to the ClawHub community API directly. Locally installed .md Skill files work as expected.

Performance & Optimization

Q: Memory usage feels high.

HexClaw renders the interface in a WebView. Normal memory usage is often around 200 to 400 MB. If it exceeds 1 GB, try the following:

• Close unneeded sessions or tabs
• Clear log cache from the Logs page
• Restart the app

Q: Where can I inspect engine health?

The Dashboard shows sidecar engine health, connection status, and API port information. Engine checks run automatically every 5 seconds.

Comparison with Other Products

Q: How is HexClaw different from ChatGPT Desktop / Claude Desktop?

ChatGPT Desktop and Claude Desktop are vendor-specific clients that only connect to their own models. HexClaw is model-agnostic — you can connect to OpenAI, Claude, DeepSeek, Gemini, Ollama, and more simultaneously, switching between them in one interface. Additionally, HexClaw includes a built-in Agent engine, MCP tool protocol, workflow canvas, and RAG knowledge base, making it a complete AI Agent runtime platform rather than just a chat client.

Q: How is HexClaw different from Cursor?

Cursor is an AI-powered code editor focused on programming. HexClaw is a general-purpose AI Agent desktop client covering conversations, Agent orchestration, workflow automation, knowledge bases, and more — not limited to code generation.

Data Management

Q: How do I back up or migrate my data?

All HexClaw data is stored in the local data directory (check Settings → General → Data Directory). To back up, simply copy this directory. To migrate to a new machine, copy the data directory to the corresponding location.

Q: How large can knowledge base documents be?

Individual documents should be under 50MB. Total knowledge base capacity depends on local disk space. Documents are automatically chunked and vector-embedded after upload, so retrieval performance is not affected by total document volume.

✏️ Edit this page on GitHub