HexClaw Docs
Agent Management
Create custom AI roles, assign prompts and tools, and coordinate multi-agent discussions.
What Is an Agent?
An agent is an AI role inside HexClaw. Each agent maintains its own:
- System prompt - defines role behavior and domain expertise
- Model binding - selects which model the agent should use
- Temperature - balances creativity against determinism
- Tool set - assigns MCP tools to that specific agent
- Skill set - enables installed skills on a per-agent basis
Create an Agent
- Open the Agent Management page
- Click "Create Agent"
- Enter a name, description, and system prompt
- Optionally bind a model, adjust temperature, and assign tools or skills
- Save the agent
Example: Create a "Frontend Expert" agent with a system prompt like "You are a senior frontend engineer specializing in Vue 3, TypeScript, and Tailwind CSS..." and set temperature to 0.3.
Agent Fields
| Field | Description |
|---|---|
| name | Unique identifier, typically in English |
| display_name | User-facing label |
| description | Short summary of the role |
| system_prompt | Core prompt that defines behavior |
| model | Bound model, or empty to use the default |
| temperature | Generation temperature from 0 to 2, default 0.7 |
| tools[] | Available MCP tools |
| skills[] | Enabled skills |
| status | active or inactive |
Chat with an Agent
On the chat page, use the agent selector above the composer to switch roles. The selected agent's system prompt is injected into the conversation automatically.
Multi-Agent Meetings
HexClaw also supports a multi-agent discussion mode:
- From the agent page, click "Agent Meeting"
- Select the agents that should participate
- Provide a topic and let the agents debate, respond, and summarize in turns
This mode works well for design reviews, multi-angle analysis, and brainstorming.
Role Details
Click any role card in the list to expand its full information:
- Backstory — the agent's background and area of expertise
- Tool list — tools and skills the role can invoke
- Constraints — restrictions the agent must follow when executing tasks
Quick Start a Conversation
Click the "Chat" button on a role card:
- A new session is created automatically, named after the role (e.g. "Data Analyst")
- Chat mode switches to Agent automatically
- Clicking the same role again navigates to the existing session instead of creating a duplicate
Agent Route Management
Use the Agent Route tab to manage model bindings for agents:
- Register — assign a Provider and model to an agent
- Edit — click ✏️ to modify the display name, Provider, or model of a registered agent
- Unregister — remove an agent route binding
Tip: When registering or editing, the name, Provider, and model fields are all required.
Role Definition Reference
Agent roles are defined in the backend hexclaw.yaml and can also be registered dynamically via the API:
roles:
- name: researcher
title: Research Assistant
goal: Conduct in-depth research on a given topic and produce a structured report
backstory: You are an experienced researcher skilled in information retrieval and analysis
tools:
- web_search
- file_write
- summary
constraints:
- All sources must be cited
- Report must be at least 1000 words