Your First OpenClaw Agent

What You Will Learn

This guide teaches you how to configure AI agents in OpenClaw. An agent is a fully isolated AI "brain" with its own workspace, settings, and session store. You will learn how to:

Configure a single agent with custom settings
Set up multiple agents for different purposes
Route messages from different channels to specific agents

What is an Agent?

An agent is an isolated AI instance with its own workspace, authentication, and session store. You can run multiple agents simultaneously, each with different models, permissions, and personalities.

Before You Start

Make sure you have:

OpenClaw installed and running on your computer
At least one channel connected (Telegram, Discord, or WhatsApp)
Successfully sent at least one message to verify everything works

Understanding the Configuration File

OpenClaw agents are configured in the openclaw.json file, typically located at ~/.openclaw/openclaw.json. The configuration uses JSON5 format, which allows comments and trailing commas.

Configuration Structure

The agent configuration has three main sections:

agents.defaults: Global default settings for all agents
agents.list: Array of individual agent configurations
bindings: Rules that route messages to specific agents

Configuring Your First Agent

Open the Configuration File

Open your OpenClaw configuration file:

bash

nano ~/.openclaw/openclaw.json

Or use your preferred editor like VS Code:

bash

code ~/.openclaw/openclaw.json

Set Default Agent Options

Add or modify the agents.defaults section to set global defaults:

javascript

{
"agents": {
  "defaults": {
    "workspace": "~/.openclaw/workspace",
    "model": {
      "primary": "anthropic/claude-sonnet-4",
      "fallbacks": ["openai/gpt-4o"]
    },
    "thinkingDefault": "low",
    "timeoutSeconds": 600,
    "contextTokens": 200000
  }
}
}

Configure Agent Identity

Give your agent a custom identity by adding to the agent configuration:

javascript

{
"agents": {
  "list": [
    {
      "id": "main",
      "default": true,
      "identity": {
        "name": "Buddy",
        "theme": "friendly assistant",
        "emoji": "🤖"
      },
      "workspace": "~/.openclaw/workspace"
    }
  ]
}
}

Restart the Gateway

After making changes, restart the Gateway to apply them:

bash

openclaw gateway

Agent Configuration Options

Model Selection

Choose which AI model your agent uses:

javascript

{
"agents": {
  "defaults": {
    "models": {
      "anthropic/claude-opus-4-5": {
        "alias": "opus",
        "params": { "temperature": 0.6 }
      },
      "anthropic/claude-sonnet-4": {
        "alias": "sonnet",
        "params": { "temperature": 0.7 }
      }
    },
    "model": {
      "primary": "anthropic/claude-opus-4-5",
      "fallbacks": ["anthropic/claude-sonnet-4"]
    }
  }
}
}

Thinking Level

Control how much reasoning the AI does:

off: No extended thinking
low: Light reasoning (default)
medium: Moderate reasoning
high: Deep reasoning for complex tasks

javascript

{
"agents": {
  "defaults": {
    "thinkingDefault": "medium"
  }
}
}

Sandbox Mode

Control code execution security:

javascript

{
"agents": {
  "defaults": {
    "sandbox": {
      "mode": "non-main",
      "scope": "agent",
      "workspaceAccess": "rw"
    }
  }
}
}

Sandbox modes:

off: No sandboxing (full access)
non-main: Sandbox non-main sessions
all: Sandbox everything

Setting Up Multiple Agents

You can run multiple agents for different purposes.

Example: Work and Personal Agents

javascript

{
"agents": {
  "defaults": {
    "model": { "primary": "anthropic/claude-sonnet-4" },
    "sandbox": { "mode": "non-main", "scope": "agent" }
  },
  "list": [
    {
      "id": "personal",
      "default": true,
      "identity": {
        "name": "Buddy",
        "theme": "friendly helper",
        "emoji": "🦥"
      },
      "workspace": "~/.openclaw/workspace-personal",
      "agentDir": "~/.openclaw/agents/personal"
    },
    {
      "id": "work",
      "identity": {
        "name": "Assistant",
        "theme": "professional assistant",
        "emoji": "💼"
      },
      "workspace": "~/.openclaw/workspace-work",
      "agentDir": "~/.openclaw/agents/work",
      "model": { "primary": "anthropic/claude-opus-4-5" }
    }
  ]
}
}

Important

Never reuse agentDir across agents. Each agent must have its own directory to avoid authentication and session conflicts.

Routing Messages to Agents

Use bindings to route messages from different channels or accounts to specific agents.

Route by Channel

Send WhatsApp messages to one agent, Telegram to another:

javascript

{
"bindings": [
  {
    "agentId": "personal",
    "match": { "channel": "whatsapp" }
  },
  {
    "agentId": "work",
    "match": { "channel": "telegram" }
  }
]
}

Route by Account

If you have multiple WhatsApp numbers, route each to a different agent:

javascript

{
"bindings": [
  {
    "agentId": "personal",
    "match": { "channel": "whatsapp", "accountId": "personal" }
  },
  {
    "agentId": "work",
    "match": { "channel": "whatsapp", "accountId": "business" }
  }
]
}

Route by Specific User

Route messages from specific users to designated agents:

javascript

{
"bindings": [
  {
    "agentId": "vip",
    "match": {
      "channel": "telegram",
      "peer": { "kind": "dm", "id": "123456789" }
    }
  }
]
}

Routing Priority

When multiple bindings match, OpenClaw uses this priority (most specific wins):

Peer match (exact user/group ID)
Guild ID (Discord servers)
Team ID (Slack workspaces)
Account ID match
Channel-level match
Default agent

Restricting Agent Permissions

Create a restricted agent for family members or public use:

javascript

{
"agents": {
  "list": [
    {
      "id": "family",
      "workspace": "~/.openclaw/workspace-family",
      "agentDir": "~/.openclaw/agents/family",
      "sandbox": {
        "mode": "all",
        "workspaceAccess": "ro"
      },
      "tools": {
        "allow": ["read", "sessions_list", "sessions_send"],
        "deny": ["write", "exec", "browser"],
        "elevated": { "enabled": false }
      }
    }
  ]
}
}

Complete Configuration Example

Here is a complete configuration with two agents:

javascript

{
"agents": {
  "defaults": {
    "workspace": "~/.openclaw/workspace",
    "model": {
      "primary": "anthropic/claude-sonnet-4",
      "fallbacks": ["openai/gpt-4o"]
    },
    "thinkingDefault": "low",
    "sandbox": { "mode": "non-main", "scope": "agent" },
    "timeoutSeconds": 600
  },
  "list": [
    {
      "id": "main",
      "default": true,
      "identity": {
        "name": "Buddy",
        "theme": "friendly assistant",
        "emoji": "🤖"
      },
      "workspace": "~/.openclaw/workspace",
      "agentDir": "~/.openclaw/agents/main"
    },
    {
      "id": "coding",
      "identity": {
        "name": "DevBot",
        "theme": "coding expert",
        "emoji": "💻"
      },
      "workspace": "~/Projects",
      "agentDir": "~/.openclaw/agents/coding",
      "model": { "primary": "anthropic/claude-opus-4-5" },
      "thinkingDefault": "high"
    }
  ]
},
"bindings": [
  { "agentId": "coding", "match": { "channel": "discord" } },
  { "agentId": "main", "match": { "channel": "whatsapp" } },
  { "agentId": "main", "match": { "channel": "telegram" } }
]
}

Troubleshooting

Agent not responding

Check that the Gateway is running and the agent configuration is valid:

bash

openclaw doctor

Wrong agent responding

Verify your bindings configuration. More specific matches take priority over general ones.

Session conflicts

Make sure each agent has a unique agentDir. Sharing directories between agents causes authentication and session problems.

What To Do Next

Now that you understand agents:

OpenClaw Glossary - Learn more terminology
Use Multiple Channels - Connect more platforms
Is OpenClaw Safe? - Security best practices

Need Help?

For more details, check the official OpenClaw documentation or the Gateway configuration guide.

Last updated: February 3, 2026 | Found an error? Contact us