Getting Started Chat & Sessions Agents Workflow Providers Advanced Shortcuts FAQ
HexClaw Docs

Getting Started

Install the app, connect a service and model, and send your first message.

System Requirements

PlatformMinimum Requirement
macOSApple Silicon or Intel; Ollama, Pandoc, and other components bundled by the current source require macOS 14 or later
WindowsWindows 10 (1809+) or later, x64
Linuxx64; release builds use Ubuntu 22.04, and the runtime needs WebKitGTK 4.1 and other Tauri dependencies

The desktop shell's configured macOS 11 minimum does not describe compatibility for bundled components. Check the assets and notes of your selected Release; the source instructions below describe the current main branch.

Installation

Option 1: One-command install (macOS, recommended)

curl -fsSL https://raw.githubusercontent.com/hexagon-codes/hexclaw-desktop/80060ab08b60b92b6cac4aa552a046b8e467c2b3/install.sh | bash

Option 2: Homebrew (macOS)

brew tap hexagon-codes/tap && brew install --cask hexclaw

Option 3: Download a release build

Visit GitHub Releases and choose the package for your platform (current version v0.5.0):

Option 4: Build from source

The quick path below is for macOS. Install Node.js ^20.19.0 || >=22.12.0, pnpm 10.30.3, Rust 1.94.0, Go 1.25.13+, Git, Make, Python 3, and curl first. For other platforms, follow the Tauri 2 prerequisites for system dependencies.

git clone https://github.com/hexagon-codes/hexclaw-desktop.git
cd hexclaw-desktop
pnpm install --frozen-lockfile
make sidecar
make render-bundle
make ollama
make dev
Tip: make sidecar uses the Makefile's HEXCLAW_REF rather than automatically selecting the latest backend. Use make sidecar HEXCLAW_REF=origin/main for the backend main branch. Other backend versions use their own go.mod requirements. See the Release workflow for Windows and Linux bundle preparation.

Welcome Wizard

The 2-step setup wizard connects a service first, then checks whether an available model is already configured:

  1. Select a service — use the app-managed local service, or enter your self-hosted cloud HexClaw address and access token
  2. Check and start — check the service connection and default model; continue the original task when ready, or open model settings if configuration is needed

After model setup, return to the original task with the content you already entered preserved. You can change the selected service's configuration later under Settings → Model services. To switch between local and cloud services, click the service status at the bottom of the sidebar.

Service modes: The app starts and stops the local service. A server manages the cloud service; cloud tasks can continue while your computer is off if the server, model, and bound IM connection remain available.

First-Time Setup

1. Configure an AI provider

Connect the selected service first, then open Settings → Model services and configure at least one available model for that service. If the cloud service already has a default model, you can start a task immediately:

Configuration file example

The local service also supports initialization via a YAML file. Configure a cloud service on its server rather than in the desktop machine's local configuration file:

# ~/.hexclaw/hexclaw.yaml
server:
  host: 127.0.0.1
  port: 16060

llm:
  default: openai
  providers:
    openai:
      api_key: sk-your-key-here
      base_url: https://api.openai.com/v1
      model: gpt-4o

platforms:
  feishu:
    enabled: false
    app_id: ""
    app_secret: ""

2. Choose a default model

Mark one model as the default chat model in the provider configuration.

3. Send your first message

Open Chat, type “Introduce the tasks you can help me complete in three sentences” in the composer, and press Enter. Model selection and reasoning settings are in the toolbar inside the bottom of the composer, with options based on the current model's capabilities. You should see streamed content finish as a complete answer; a successful connection test alone does not show that a task has completed.

First Troubleshooting Steps

If the app launches but you still cannot chat successfully, check these three items first:

  1. Open Settings → Model services and run Test Connection on the active provider
  2. In local mode, open the Logs page and confirm the Engine is running and default port 16060 is free; in cloud mode, check the service address, access token, and server status
  3. If you still see a blank window, 401/403 errors, or MCP failures, go straight to the FAQ

Application Architecture

HexClaw Desktop is built on a Tauri v2 + Vue 3 + Go sidecar stack:

Data ownership: The selected service stores conversations, learning records, model settings, and connections. Switching does not migrate or merge data. Online models receive the content sent to them for a task, and data handling depends on the chosen provider. Cloud tools access the server environment rather than automatically gaining access to local files.

Interface Overview

HexClaw's sidebar is organized as "Chat pinned + Build / Connections / System". The app opens straight into Chat; jump anywhere with the ⌘+K command palette or ⌘+number:

PageGroupPurpose
ChatPinnedOne composer, current-agent context, model and reasoning settings, streaming output, Artifact previews, document parsing, voice input
AgentsBuildCreate and manage agent roles; edit the default assistant persona (SOUL)
KnowledgeBuildTwo tabs: Documents (RAG retrieval) and Memory (cross-session semantic memory)
AutomationBuildThree tabs: Scheduled Jobs (Cron), Webhooks, and Workflows
ConnectionsConnectIM channels and accounts, email, and connectors for document platforms, databases and files (such as GitHub, MySQL and local files)
CapabilitiesConnectThree tabs: Skills (ClawHub marketplace), MCP servers, and the Prompt library
LogsSystemLive WebSocket log stream with trace_id tracking
SettingsSystemModel providers, automation permissions, and system settings such as appearance and notifications
Tip: There's also a global Quick Chat floating window — press ⌘+⇧+H to summon it anywhere.
Chat & Sessions →

✏️ Edit this page on GitHub