Agents

Agents are the core of your ClawHQ deployment. Each agent is a specialized AI persona configured to handle specific tasks — from customer support to content creation. This page covers how to deploy, monitor, test, and manage your agents.

Agent Cards

The agents page displays each agent as an individual card in a responsive grid layout. Every agent card shows:

• Agent name and a short description of its purpose.
• Category — The type of agent (Support, Sales, Research, Content, Data, Manager, Reviewer).
• Deployment status — A clear badge indicating whether the agent is Deployed (green) or Not Deployed (gray).
• Deploy/Undeploy button — A single-click action to change the agent's deployment state.

Deployed agents are actively running on your VPS and ready to handle conversations. Not-deployed agents exist in your library but are not consuming resources or processing messages.

Agent Health Status

Each deployed agent is continuously monitored for health. The health indicator appears as a colored dot on the agent card with one of four possible states:

• Healthy (green) — The agent directory exists on the VPS, the gateway is responding, and the agent successfully responds to ping requests.
• Degraded (yellow) — The agent is partially functional. For example, the directory exists and the gateway responds, but the agent is slow to respond to pings.
• Error (red) — The agent has failed one or more health checks. Common causes include a missing agent directory, gateway errors, or the agent process crashing.
• Unknown (gray) — Health status cannot be determined, typically because the VPS is stopped or unreachable.

Health checks are performed via SSH to your VPS. The system verifies three things in sequence: that the agent's directory exists on disk, that the OpenClaw Gateway is responding on port 18789, and that the specific agent responds to a lightweight ping message.

Quick Test Dialog

You can test any deployed agent directly from the agents page without navigating to the Chat interface. Click the "Test" button on an agent card to open the quick test dialog.

The quick test dialog provides a lightweight chat window where you can send up to 5 test messages to the agent and see its responses in real time. This is useful for:

• Verifying that a newly deployed agent is responding correctly.
• Spot-checking an agent's behavior after configuration changes.
• Testing specific prompts or edge cases without starting a full conversation.

Test conversations are not saved to your conversation history and do not count toward any usage metrics.

Agent Configuration View

Each agent's configuration is accessible through a tabbed interface on the agent detail panel. The configuration is organized into four tabs:

• SOUL.md — The agent's personality definition, including its tone, style, and behavioral guidelines.
• identity.md — The agent's identity information, such as its name, role description, and greeting messages.
• TOOLS.md — The list of tools and capabilities available to the agent, such as web search, file reading, or API calls.
• config.json — Technical configuration parameters including temperature, max tokens, and other model-specific settings.

For Starter plan users, the configuration view is read-only. You can inspect how each agent is configured but cannot modify the files directly. Pro and Ultra plan users have full editing capabilities through the Agent Builder, which provides a guided interface for modifying agent configurations.

Per-Agent Statistics

Each agent card displays a statistics line with three key metrics, calculated over the trailing 7-day period:

• Messages (7d) — The total number of messages the agent has processed in the last 7 days.
• Avg Response Time — The average time in seconds between receiving a message and delivering the complete response.
• Last Active — A relative timestamp showing when the agent last processed a message (e.g., "2 hours ago", "3 days ago").

These metrics help you quickly identify which agents are actively handling traffic and how well they are performing. An agent with a high message count but increasing response times may benefit from a model switch to a faster model.

Agent Logs

The agent logs panel shows the last 10 message exchanges for each agent. Each log entry includes:

• The incoming user message.
• The agent's response.
• The response time for that exchange.
• The timestamp of the conversation.
• The channel through which the message was received (WhatsApp, Telegram, web, API, etc.).

Logs are useful for debugging agent behavior and understanding how agents respond to real user queries. For a complete conversation history, use the Chat page.

Bulk Actions

The bulk actions dropdown at the top of the agents page lets you perform operations on multiple agents simultaneously:

• Deploy All Undeployed — Deploys every agent in your library that is not currently deployed. Useful when setting up a new instance or recovering from a full reset.
• Undeploy All — Removes all agents from active deployment. The agent configurations are preserved in your library.
• Restart All — Restarts every deployed agent without changing their deployment state. This is equivalent to undeploying and redeploying each agent.

Bulk actions execute sequentially to avoid overloading your VPS. A progress indicator shows how many agents have been processed out of the total.

Sorting and Filtering

The agents page includes controls for organizing your agent list:

• Filter by status — Show all agents, only deployed agents, or only undeployed agents.
• Filter by category — Narrow the list to a specific agent category (Support, Sales, Research, etc.).
• Filter by activity — Show only agents that have been active in the last 24 hours, 7 days, or 30 days.
• Sort options — Sort by name, deployment status, message count, response time, or last active timestamp.

Grouping by Category

When you have many agents, you can enable category grouping to organize the agent grid into labeled sections. Each section has a header showing the category name and the count of agents in that category (e.g., "Support (3)", "Research (2)").

Category groups are collapsible, allowing you to focus on a specific type of agent while hiding the rest. Your grouping preference is saved and persists across sessions.

Related Documentation

• Agent Store — Browse and install new agents.
• Chat — Have full conversations with your deployed agents.
• AI Models — Change the AI model powering your agents.
• VPS Management — Monitor the server running your agents.
• Dashboard Overview — See agent metrics on the main dashboard.