FAQ

Installation & Startup

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

First distinguish a UI loading problem from a service connection problem, then check the selected service:

1. Inspect Logs for startup or connection errors
2. For local service, check that the sidecar started and port 16060 is available
3. For cloud service, check the service URL, access token, and server status; restarting the desktop app does not restart the server

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 → System → 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.

In Settings → Model services, check the provider, URL, credentials, and model access used by the current service, then inspect the provider's specific error. The status code alone does not establish that the account lacks funds.

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

Make Ollama and a downloaded model available to the selected HexClaw service, then add an Ollama provider. macOS packages include Ollama; Windows and Linux require a separate installation for local models:

• Base URL: http://localhost:11434/v1
• API Key: leave empty
• Model: enter the name of a model actually downloaded in Ollama

Here, localhost means the machine running the HexClaw service. For cloud service, that is the server, not your desktop. Using a local model does not make web search or external tools work offline.

Q: Streaming output seems stuck.

Inspect task progress, tool activity, and the current service's logs to distinguish ongoing model processing, a dropped connection, and a confirmed failure. You can stop the current request; supported tasks resume through the original request. If the outcome is unknown, check the original task and existing artifacts before repeating an operation that may incur charges or external effects.

Data & Privacy

Q: Where is my data stored?

Business data belongs to the selected HexClaw service:

• Local service: sessions, learning records, knowledge documents, and generated files are stored on this device.
• Cloud service: that business data and service configuration are stored on your server.
• Model credentials: local provider settings and API keys are stored in ~/.hexclaw/hexclaw.yaml; cloud service uses its server configuration. Local provider keys are not stored in the operating system keychain.
• Desktop preferences: appearance and other desktop settings are managed separately from service data. Confirm the selected service and its data location in Settings.

Switching between local and cloud service does not automatically migrate or merge conversations, learning records, model settings, or connections.

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

Online models receive the questions, images, document contents, and context required for the task. Web search, MCP servers, messaging channels, and other external tools also receive the content their operations require. Ollama can run model inference locally, but whether a whole task stays offline depends on its tools and services.

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?

Participation depends on the running service and configured agents. Choose roles with clear responsibilities for the task. More participants add context and model calls; they do not guarantee a better result.

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 Thinking

Does enabling deep thinking automatically search the web?

Thinking settings control the reasoning capability supported by the model. Web search needs an available tool and an actual invocation. Inspect tool activity and sources to distinguish model reasoning from retrieved evidence. If a tool has no final result, inspect the original task status first.

The Deep Thinking output quality is not satisfactory.

Try the following:

• Choose a model suited to the task with the required reasoning support
• Provide a more specific research topic and scope
• Specify the desired output format in your prompt (e.g. "generate a Markdown report with citations")

Connections · IM Channels

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

1. In Connections, check the channel configuration and connection status of the current service; follow any channel-specific reconnection instructions
2. Verify the App Secret / Token (note: test and production credentials may differ)
3. Check receiving permissions and the target conversation binding; K12 tutoring uses a bound one-to-one parent-to-bot chat
4. Check the Logs page for connection errors

Skill Marketplace

A skill installed from ClawHub does not take effect.

The marketplace searches and installs skills through the selected HexClaw service. In Capabilities → Skills, check whether the skill is installed and enabled, then inspect the agent's skill configuration, dependencies, and run records. Inspect specific installation or network errors; seeing a marketplace entry does not mean it was installed. Local-file and URL installation are also available.

Performance & Optimization

Q: Memory usage feels high.

Distinguish memory used by the desktop WebView, the HexClaw service, and local model processes. Long conversations, media previews, document processing, and model size all affect requirements. You can:

• Close media previews you are not using
• Check active tasks and local model processes to identify the source of usage
• If usage remains abnormal after tasks finish, keep relevant logs and restart the affected app or service

Q: Where can I inspect engine health?

The service card in Settings shows the selected local or cloud service and its connection status. Logs provides execution details, and About shows desktop, backend, and component versions. A connected service does not prove a particular task or delivery completed.

Comparison with Other Products

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

HexClaw is an open-source agent workspace connected to a local or self-hosted cloud service. It brings multiple model providers, knowledge documents, MCP, Skills, and automation into one interface. Compare your tasks, deployment needs, models, and tools; consult each other product's current official documentation for its capabilities and terms.

Q: How is HexClaw different from Cursor?

HexClaw supports general task delegation, including document work, media generation, knowledge retrieval, automation, and homework tutoring. Assess a development task against the connected tools, execution environment, and actual artifacts; generating code alone does not establish that it replaces a complete development environment.

Data Management

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

First identify whether the data belongs to local or cloud service. A full service backup must cover that deployment's actual databases, document and artifact directories, and configuration using its backup and recovery procedure. Copying desktop preferences is not a business-data backup. Conversations can be exported, and family learning profiles support .hexbak archives and recovery. Switching services does not migrate data; keep model credentials and other configuration separately protected.

Q: How large can knowledge base documents be?

Follow the current service's file requirements and upload feedback. Capacity and processing time depend on the service machine's disk, document contents, parsing, and index configuration. Check processing progress after upload and use retrieval once the document is ready. Document volume and index size also affect resource usage and retrieval performance.

✏️ Edit this page on GitHub