What HQ includes

HQ is an agent operations system, not just an agent chat UI. It gives you a workspace for CRM, tasks, knowledge, routines, collections, and a fleet of long-lived AI agents that run on infrastructure you control. This page is the product tour. For system internals, read Architecture. For installation, read Installation.

​

At a glance

​

Workspace

Every HQ install connects to one or more Supabase projects. A workspace contains all the data: agents, tasks, CRM records, knowledge, routines, collections, settings, gateway registrations, command history, and usage data. The first boot flow is intentionally config-light:

1. Start the Docker stack (self-hosted) or sign up (hosted).
2. Open the UI and sign in.
3. Complete the onboarding wizard.

After setup, the workspace can be managed from Settings. The UI stores workspace metadata in /config/workspaces.json and workspace secrets in /config/secrets.json on the ui-config volume. The active workspace is selected at runtime, so the published UI image does not need a rebuild for each user’s Supabase project.

​

Onboarding

The onboarding wizard consolidates all first-boot setup into a single guided flow:

1. Welcome — workspace name and owner profile.
2. Intent — pick a use case (outreach, deals, hiring, publishing, ops, explore). Seeds a context preset with pipeline stages, fields, and streams.
3. Infrastructure (self-hosted only) — connect Supabase (URL + keys) and choose gateway placement (local Docker or remote server).
4. Model provider — connect Anthropic, OpenAI, or Ollama with a BYO API key.
5. First agent — create an agent from the recommended template and optionally connect a messaging channel.

After the wizard, a Mission Panel tracks progressive onboarding (assign a task, add knowledge, create a second agent, etc.) and auto-dismisses when complete. See Workspace setup for full details.

​

Dashboard

The dashboard is the operating view for the workspace. It summarizes:

• Agent fleet health.
• Gateway status.
• Open tasks and streams.
• Recent activity.
• Notifications.
• Fleet usage and budget status.

The dashboard is backed by Supabase realtime subscriptions, so most operational changes appear without a full refresh.

​

Agents

An HQ agent is a long-lived workspace — not a chat wrapper. Agents are created from templates under templates/. The creation wizard lets you choose a template, set identity fields, select a manager, choose a messaging channel, enter credentials, and watch the gateway provisioning command run. The agent detail page includes:

• Overview — status, capabilities, knowledge items, skills, direct reports, and routines.
• Secrets — credentials and keys this agent can use, with inherited gateway secrets and per-agent overrides.
• Files — file browser/editor for the agent’s git branch.
• Browser — remote desktop access through the assigned gateway.
• Activity — usage summary, inbox history, and command/operation history.
• Model and thinking level — pick any connected model and reasoning depth from the right rail. Changes take effect on the next wake, no restart needed.

​

Agent Templates

Templates are role-specific starting points for agents. The repository ships 16 templates: default, analytics, assistant, chief of staff, CMO, cofounder, CRM researcher, designer, ghostwriter, market researcher, newsletter editor, newsletter writer, sales copywriter, script writer, social strategist, and social writer. Each template includes files such as:

• agent.json for runtime metadata.
• IDENTITY.md for role, voice, and domain behavior.
• SOUL.md for goals and non-negotiables.
• USER.md for owner profile placeholders.
• MEMORY.md and memory/ for persistent context.
• TOOLS.md for tool-use guidance.
• skills/ for repeatable procedures and scripts.

When the gateway boots for the first time, it seeds each template into the local bare repo as a template/<name> branch. Provisioning an agent creates a new branch from the selected template and commits the personalized files.

​

Agent Files and Memory

Agent source of truth is the gateway worktree. Agents can update their own files during work, and the operator can edit files from the UI. The file browser talks to the gateway files API. Every create, edit, or delete is committed to git, then the UI enqueues an update command so the gateway reloads the agent. Typical memory files:

• MEMORY.md for curated long-term memory.
• memory/YYYY-MM-DD.md for daily notes.
• history/ files for longer work narratives.
• Skills under skills/ for reusable procedures.

Optional git remote sync can push commits to GitHub or another git host for backup.

​

Agent Organization and Delegation

Agents can report to other agents through agents.reports_to_id. The UI prevents self-reporting and cycle creation. The agents list has a Fleet / Org chart view toggle that appears once at least one agent has a manager. The chart renders the reporting tree as connected boxes with collapsible subtrees. On each agent’s detail page, the sidebar shows an “Org” section with the agent’s manager, peers, and direct reports — the manager pill opens a picker for inline reassignment. Runtime boot context includes:

• The agent’s manager.
• The agent’s direct reports.
• Delegation rules.

The intended operating model is:

• Delegate to direct reports by assigning tasks.
• Escalate to a manager by creating a high-priority task.
• Ask the human before routing work to peers outside the direct hierarchy.

​

Usage Tracking and Budgets

HQ records LLM usage in agent_usage and rolls it up into agent_budgets. The budget system tracks:

• Provider and model.
• Input, output, cache-read, and cache-write tokens.
• Estimated cost when pricing is known.
• Current monthly spend.
• Metered and unmetered calls.
• Soft threshold warnings.
• Hard cutoff status.

Budgets can be configured per agent. When a hard cutoff is enabled and an agent exceeds its monthly limit, the runtime blocks further replies and the inbox dispatcher stops waking that agent for background work. Budget transitions also create notifications.

​

Secrets Management

Agents need credentials — API keys, OAuth tokens, webhook secrets — to interact with external services. HQ provides a unified encrypted secrets system that stores, syncs, and injects these values securely. Settings → Secrets manages workspace-level credentials available to all agents. The agent detail → Secrets tab shows per-agent overrides and inherited gateway secrets. Three categories:

• User — manually added API keys and credentials (e.g. SALESFORCE_API_KEY).
• Channel — auto-created when an agent is provisioned with a messaging channel (e.g. TELEGRAM_BOT_TOKEN).
• Integration — auto-created by OAuth flows (e.g. Notion access tokens for source sync).

Secrets are delivered to agents as environment variables via per-agent .env files on the gateway filesystem. Agent tools read them with os.environ.get("SECRET_KEY"). The AI model never sees secret values — only the tools it runs can access them. For details on encryption, key derivation, and the sync protocol, see Secrets management.

​

CRM

The CRM stores people, organizations, interactions, campaigns, message templates, and draft sets. Core capabilities include:

• Contacts and organizations.
• Contact-organization relationships.
• Interaction timeline.
• Dynamic custom fields.
• Pipeline stages and kanban views.
• Import wizard with mapping and duplicate handling.
• Campaign and draft workflows.
• Routine triggers that can assign work to agents.

CRM records are regular Supabase rows. Agents can read and update them through the bundled HQ skills.

​

Tasks

Tasks are the main coordination primitive between the human and agents. Tasks support:

• Human, agent, or system assignees.
• Streams for grouping work.
• Statuses such as todo, in progress, blocked, done, cancelled, and missed.
• Priorities and due dates.
• Recurrence rules.
• Per-task model and thinking overrides — when assigned to an agent, override the model or reasoning depth for this specific execution without changing the agent’s default.
• Relations and dependencies — link tasks with blocked_by, blocks, relates_to, parent_of, and child_of relationships. Blockers are highlighted in the task list and task form. When a blocking task completes, a notify_blocker_resolved trigger creates an inbox item for the unblocked task’s assignee.
• Labels — managed workspace labels with configurable colors. Labels can be created from Settings → Labels or inline from the task form. Tasks display label pills in list and board views, and a label filter is available in the toolbar.
• Deliverables — agents submit work products (pages, URLs, or collection records) to tasks for human review. The review workflow supports approve, request revision (with note), and reject actions. Deliverables appear in the task form’s Deliverables tab.
• Task templates — reusable task group templates with dependency graphs. Create templates from Settings → Templates, then spawn them from the task toolbar. Dependencies between template items are preserved as blocked_by relations on the created tasks.
• Overdue escalation — a pg_cron job marks tasks past their due date as missed and creates inbox items to notify assigned agents. The task form shows a missed-task banner with a reopen action.
• Comments and mentions.
• Entity links to knowledge items, contacts, organizations, collection records, and URLs.
• Agent inbox wakeups on assignment and reassignment.
• Agent delegation — agents can delegate subtasks to direct reports via hq_delegate_task.py, which validates the org-chart relationship, creates a subtask with child_of relation, and inherits the parent task’s stream.

Mentioning an agent in a comment creates an inbox item for that agent. Assigning a task to an agent does the same. Per-task model overrides are carried through the inbox item’s context and passed to the agent session at wake time. The inbox dispatcher enriches task assignment items with unresolved blocker information so agents know what dependencies exist before starting work.

​

Knowledge

The knowledge system is the unified store for all workspace knowledge. It replaces the earlier separate documents and assets models with a single knowledge_items table supporting four kinds:

• Pages — rich-text documents (company briefs, style guides, meeting notes).
• Skills — structured procedures and SOPs.
• Files — uploaded files (PDFs, images, spreadsheets, audio, video).
• Sources — externally synced content from connected integrations via the plugin-based source connector system.

Knowledge items support folders, tags, pinned state, rich editing, and semantic + full-text search. Source connectors are self-contained plugins — each provider is a folder under gateway/connectors/<provider>/ with a manifest.json that declares auth, UI metadata, and capabilities. The platform handles credential encryption, OAuth flows, UI forms, sync scheduling, and embedding automatically. Providers that support it can enable two-way sync with a writable toggle per connection. See Knowledge system — Source connectors for the architecture. Agent boot context is controlled by scope and pinning:

• A workspace-scoped, pinned item is included in every agent’s startup context.
• An agent-scoped item assigned to specific agents is included only for those agents.

See Knowledge system for the full architecture and Knowledge and agent context for the practical guide.

​

Routines and Inbox

Routines convert workspace events and schedules into agent work. Each routine has a trigger (event-based or schedule-based) and an assigned agent. Supported event triggers include:

• Contact created.
• Contact status changed.
• Contact fields updated.
• Task assigned or reassigned.
• Agent mentioned in a comment.

Schedule triggers run on a cron schedule (e.g. every 15 minutes, hourly, daily) and wake the assigned agent at each interval. Routines create agent_inbox_items. The gateway dispatcher leases pending inbox items, checks whether the target agent belongs to that gateway, verifies budget status, and wakes the agent through OpenClaw. Inbox items have retry state, attempt counts, lease fields, done/failed/dead-letter statuses, and deduplication keys.

​

Gateways

A gateway is a Docker host that runs agents. One workspace can have multiple gateways. The gateway stack includes seven services (all behind the gateway Compose profile):

• Gateway container with OpenClaw, Chrome/Chromium, XFCE, noVNC, and the files API.
• Dispatcher daemon for agent inbox work.
• Runner daemon for lifecycle and operations commands.
• Embedder daemon for knowledge indexing and vector search.
• File processor daemon for extracting text from uploaded files (PDF, DOCX, XLSX, etc.).
• Plugin runner daemon for dispatching workspace events to local and webhook plugins.
• A shared gateway-state volume for OpenClaw config, git repo, worktrees, browser profiles, desktop files, plugins, and auth state.

The Settings -> Gateways UI supports:

• Viewing gateway status and stale heartbeats.
• Adding a gateway with a single-use registration token.
• Generating a curl | bash installer command for a remote host.
• Removing gateways.
• Editing labels and reachable URL overrides.
• Opening the noVNC desktop modal.

​

Provider Connections and Models

HQ is model-agnostic. Agents work with whatever provider you connect — there is no required or default provider. Model provider auth is managed from Settings → Connections and from the agent rail. The command runner handles auth flows through agent_commands. When the same models are available through multiple connections (e.g. OpenAI API key and OpenAI subscription), HQ unifies them into a single provider group. If both are connected, models appear with route labels (“Subscription” / “API”) so you can choose which billing path to use. Subscription-only models like Codex Mini only appear when that connection is active.

​

Model Selection

Every agent can run a different model and thinking level — no gateway restart needed, no global config change. This is a core design choice: a fleet of agents should be able to mix expensive reasoning models for complex work with fast cheap models for simple lookups.

​

How it works

Resolution is bottom-up: task override wins over agent default, which wins over workspace default.

​

Thinking levels

For models that support extended reasoning (Claude, o-series), HQ exposes a thinking level selector:

​

Multi-route providers

Some providers serve the same models through different billing paths. OpenAI models (GPT-4.1, o3, o4-mini) are available both via API key (pay-per-token) and via ChatGPT subscription (included in your plan). HQ handles this transparently:

• One connection: Models appear under “OpenAI” with no qualifier.
• Both connections: Each model appears twice with “Subscription” (preferred) and “API” route labels. Choose which billing path each agent uses.
• Exclusive models: Codex Mini is subscription-only and only appears when that connection is active.

See Connect a model provider for setup and Inbox dispatch for how overrides reach the agent runtime.

​

Networking

HQ’s default networking model is host-controlled:

• Local mode binds services to loopback.
• Tailscale mode installs or uses Tailscale on the host, not inside containers.
• Public mode expects a host-level reverse proxy or tunnel.

Gateways register their reachable URLs in Supabase so the UI can open the correct files API and noVNC endpoint for each gateway.

​

Notifications and Activity

HQ records important workspace events in notifications, audit_log, command history, inbox history, and activity feeds. Examples include:

• Budget warnings and exceedances.
• Command completion or failure.
• Agent lifecycle actions.
• Task and CRM events.
• Gateway state changes.

This gives the operator a single place to understand what happened and why.

​

Plugins

HQ has a built-in plugin system for reacting to workspace events. Plugins can send Slack notifications when tasks complete, sync data to Linear, trigger webhooks for Zapier, log budget alerts, or run any custom logic. 16 built-in events cover tasks, agents, knowledge, inbox, routines, comments, secrets, usage, and budgets. The plugin runner daemon dispatches events to all matching plugins in real time. Manage plugins from Settings → Plugins — enable/disable, configure, view event logs, and add new webhook plugins from the UI. See Plugins for the full architecture and Plugin events for the event reference.

​

Extensibility

Most customization does not require changing code:

• Add templates under templates/.
• Add skills to templates.
• Configure fields, pipeline stages, streams, and routines in the UI.
• Add model providers through connections.
• Add gateways through Settings.
• Add webhook plugins from Settings → Plugins (no code needed).

Code extension points include:

• New UI pages under apps/ui/src/app.
• New gateway command actions in gateway/daemons/command_runner.py.
• New routine behavior in database functions/triggers.
• New agent skills under template skills/.
• New OpenClaw plugins in gateway/scripts/plugins/.
• New source connectors under gateway/connectors/<provider>/ — copy the _template/ directory and implement the connector interface. See CONTRIBUTING-SOURCES.md.
• New HQ plugins under gateway/plugins/<id>/ — copy _template/, implement on_event(), and subscribe to events. See gateway/plugins/CONTRIBUTING.md.