Agent Customization

📘 Guide Status: This page covers how to define and customize AI agents in OpenClaw. For first-time setup, see the Quick Start Guide and the configuration file guide.

Overview

OpenClaw is an autonomous AI agent platform: the gateway daemon manages connections, routing, and the agent lifecycle. Unlike a single chatbot, you can run one default agent or create multiple agents with different personalities, models, skills, and behaviors-each suited to specific channels or use cases.

This guide covers:

Prerequisites

How OpenClaw Agents Work

The OpenClaw Gateway is the background service that manages connections to messaging platforms (WhatsApp, Telegram, Discord, Slack, and 15+ others), routes messages, and runs the agent lifecycle. Each agent is the “brain” that processes user messages, decides which tools or skills to use, and can execute tasks (browser control, files, shell, email, calendar, etc.) 24/7.

By default you typically have one agent that handles all channels. You can instead define multiple agents and assign them to different channels or contexts-for example, a “support” agent with a formal tone and specific skills, and a “personal” agent with a casual tone and different skills. Each agent can have its own system prompt, model, and skill set.

Agent Configuration in the Config File

Agent definitions live in your main OpenClaw configuration file. Use openclaw config edit or edit the file directly (see file structure for location). Typical options per agent include:

  • System prompt: Instructions that define the agent’s role, tone, and behavior (e.g. “You are a helpful coding assistant” or “You are a concise customer support bot”).
  • Model: Which LLM to use (Claude, GPT, Gemini, DeepSeek, or local models via Ollama). Configured under model providers; each agent can use a different model.
  • Skills: Which ClawHub skills or custom skills are enabled for this agent (email, browser, files, etc.).
  • Tools / tool policy: Allowlists or denylists for tools (file access, shell, browser). Restrict high-risk tools in production-see sandbox and tool policies in the advanced guide.
  • Memory: Whether the agent uses the global memory system and how much context is retained across sessions.

Exact keys and schema depend on your OpenClaw version. Refer to the official OpenClaw documentation for the current agent config schema.

Creating Multiple Agents

To run more than one agent, define each agent in your config with a unique identifier (e.g. name or ID). You can then:

  • Assign agents to channels: e.g. Telegram uses “support” agent, Discord uses “personal” agent.
  • Vary personality and tone: one agent formal and task-focused, another casual and creative.
  • Limit capabilities per agent: give one agent only read-only file access and another full automation skills.

This is useful for business automation (separate support vs sales agents), content creation (researcher vs writer agents), or development (code-review vs deployment agents). For orchestrated “teams” of agents, see multi-agent use cases and the use cases hub.

Model and Skills per Agent

Model: Each agent can use a different LLM. For example, use a fast local model (via Ollama) for simple Q&A and a powerful cloud model (e.g. Claude or GPT) for complex reasoning or code. Set the model in the agent’s config block; ensure the provider is configured under model providers.

Skills: Install community skills from the ClawHub marketplace or create custom skills. Per agent, you can enable only the skills that agent needs-e.g. a support agent gets email and calendar skills; a dev agent gets browser and shell skills. Restrict untrusted skills and run openclaw security audit; see skills security and security best practices.

System Prompts and Behavior

The system prompt sets the agent’s role, tone, and constraints. Good prompts include:

  • Role (e.g. “You are a technical support assistant for OpenClaw users.”)
  • Tone (e.g. “Be concise and professional.” or “Be friendly and casual.”)
  • Scope (e.g. “Only answer questions about OpenClaw installation and configuration.”)
  • Safety (e.g. “Do not execute destructive commands without user confirmation.”)

Experiment in a test channel before rolling out to production. For prompt engineering tips and examples, see the official documentation and video tutorials.

Memory and Context

OpenClaw’s memory system provides persistent context across sessions and channels. Per agent you can control how much history is kept, whether memory is shared across agents, and retention rules. Long context can improve coherence but increase latency and cost; tune according to your performance and model limits.

Multi-Agent Use Cases

Advanced setups use multiple agents working together: e.g. a “CEO” orchestrator that delegates to specialist agents (researcher, writer, reviewer), or a content pipeline (researcher → writer → editor). OpenClaw supports such patterns through multiple agent definitions and channel or workflow routing. For inspiration and examples, see the use cases library (business, content creation, development) and the community showcase. Building and selling multi-agent workflows is also a common monetization path.

Security: Sandbox and Tool Policies

Agents that can run shell commands, access files, or control browsers are powerful but risky. For production:

  • Enable sandbox mode and use tool allowlists so each agent only has the tools it needs.
  • Avoid giving every agent full system access; restrict dangerous commands (e.g. raw shell) or require human approval where supported.

Configure these in advanced configuration (tool policies and sandbox). Follow the security best practices and security checklist.

Quick Agent Configuration Workflow

  1. Ensure OpenClaw is running: openclaw status
  2. Edit config: openclaw config edit (or edit the config file; see file structure)
  3. Add or modify agent blocks (system prompt, model, skills, tool policy)
  4. Restart the gateway so changes apply (e.g. openclaw gateway restart or restart the service)
  5. Verify: openclaw status and test the agent on a channel

Common Issues

Issue Solution
Agent not responding Check gateway and channel connection; verify agent is assigned to the channel; see troubleshooting
Wrong model or model not found Confirm model name matches a configured model provider; check API keys and billing
Config validation failed / agent config moved Check YAML/JSON syntax and schema; run openclaw doctor; see official docs and troubleshooting
Agent ignores system prompt Ensure system prompt is in the correct config key for your version; try a shorter, clearer prompt; check model context limits
Skills not available to agent Confirm skills are installed and listed in the agent’s skill config; check skills security and allowlists in advanced config
Authentication or API errors Verify API keys for the model provider; see model providers and troubleshooting

For more solutions, see our full troubleshooting guide.

Best Practices

  • Start with one agent and one channel; add more agents once the default works well
  • Use security hardening: sandbox, tool allowlists, and safe credential handling
  • Give each agent a clear role and minimal required skills to reduce risk and confusion
  • Back up config files before major changes; test new agents in a dev channel first
  • Keep OpenClaw and skills updated; monitor logs for errors or unexpected behavior

Next Steps

Related Resources

FAQ

Can I have different agents for different channels? Yes. In your config you can define multiple agents and assign each to specific channels (e.g. Telegram → support agent, Discord → personal agent). See the official docs for the exact schema.

How do I change an agent’s personality? Edit the agent’s system prompt in the config file. Describe the role, tone, and constraints. Restart the gateway and test on a channel.

Should I use sandbox mode for each agent? Yes for production. Sandbox and tool allowlists limit what each agent can do and reduce risk from prompt injection or misuse. See security best practices and advanced config.