DEV Community

linou518
linou518

Posted on • Edited on

OpenClaw Guide Ch.3: Your First Agent

#ai #opensource #tutorial #devops

Chapter 3: Your First Agent

🎯 Learning Objective: Successfully create and configure your first AI Agent and perform basic conversational interactions

🤖 What Is an Agent?

In OpenClaw, an Agent is an AI instance with a unique identity, memory, and capabilities. Each Agent functions like a dedicated AI assistant that can:

  • 🧠 Maintain independent memory and learning capabilities
  • 🛠️ Use a specific set of tools
  • 📁 Manage its own workspace
  • 💬 Interact with users across different channels
  • 🎯 Focus on specific task domains

🏗️ Agent Configuration Structure

Basic Configuration Template 

{
  "agents": [
    {
      "id": "my-first-agent",              // Unique identifier
      "name": "My First Assistant",         // Display name
      "model": "anthropic/claude-sonnet-4", // AI model
      "systemPrompt": "You are a...",       // System prompt
      "workspace": {
        "root": "./agents/my-first-agent"   // Working directory
      },
      "memory": {
        "enabled": true,                    // Enable memory
        "maxTokens": 50000                  // Memory capacity
      },
      "tools": {
        "allowlist": ["read", "write", "exec"] // Allowed tools
      }
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Configuration Field Reference

Field Required Description Example
id ✅ Unique Agent identifier "main", "coding-assistant"
name ❌ Display name "Coding Helper", "Life Manager"
model ✅ AI model "anthropic/claude-sonnet-4"
systemPrompt ❌ System prompt Defines the Agent's role and behavior
workspace.root ❌ Working directory "./agents/coding"
tools.allowlist ❌ Tool allowlist ["read", "write", "exec"]

🎯 Hands-On: Creating Your First Agent

Step 1: Plan the Agent's Role

Let's create a "Personal Assistant" Agent with these capabilities:

  • 📅 Schedule management and reminders
  • 📝 Note-taking and organization
  • 🌐 Information search and summarization
  • 💻 Basic file operations

Step 2: Create the Workspace 

# Navigate to the OpenClaw workspace
cd ~/.openclaw/workspace-main

# Create an Agent-specific directory
mkdir -p agents/personal-assistant
cd agents/personal-assistant

# Create the basic file structure
mkdir -p {memory,logs,projects}
touch MEMORY.md SOUL.md USER.md
Enter fullscreen mode Exit fullscreen mode

Step 3: Write the Agent Configuration

Edit ~/.openclaw/workspace-main/openclaw.json:

{
  "gateway": {
    "port": 18789,
    "bind": "loopback"
  },
  "agents": [
    {
      "id": "personal-assistant",
      "name": "Personal Assistant",
      "model": "anthropic/claude-sonnet-4-20250514",
      "systemPrompt": "You are a professional personal assistant AI. Your job is to help the user manage daily tasks including scheduling, information retrieval, and file management. You should:\n\n1. Be proactive, efficient, and friendly\n2. Remember the user's preferences and habits\n3. Provide practical suggestions and solutions\n4. Protect user privacy and data security\n\nReply concisely and clearly, using structured formats (lists, tables) when appropriate.",
      "workspace": {
        "root": "./agents/personal-assistant"
      },
      "memory": {
        "enabled": true,
        "maxTokens": 100000
      }
    }
  ],
  "auth": {
    "profiles": [
      {
        "id": "anthropic",
        "provider": "anthropic"
      }
    ]
  },
  "tools": {
    "allowlists": {
      "personal-assistant": [
        "read",
        "write",
        "exec",
        "web_search",
        "memory_search",
        "memory_get",
        "sessions_list",
        "cron"
      ]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Step 4: Create Agent Identity Files

SOUL.md — Agent Personality 

# SOUL.md — Personal Assistant Personality

## Core Traits
- 🎯 **Proactive**: Anticipates user needs and offers helpful suggestions
- 🧠 **Smart & Efficient**: Quickly understands instructions, provides precise solutions
- 😊 **Friendly & Thoughtful**: Warm communication style, cares about the user
- 🔒 **Trustworthy**: Protects privacy, executes tasks reliably

## Communication Style
- Uses concise, clear language
- Presents important information in structured formats
- Uses emoji appropriately for a personal touch
- Always maintains professionalism and courtesy

## Working Principles
1. **User First**: The user's needs and preferences are the top priority
2. **Think Ahead**: Don't just answer questions — offer relevant suggestions
3. **Continuous Learning**: Remember user habits, continually improve service
4. **Safety First**: Protect user data and privacy
Enter fullscreen mode Exit fullscreen mode

USER.md — User Information 

# USER.md — User Information

## Basic Info
- **Name**: [User Name]
- **Timezone**: Asia/Shanghai
- **Language**: English
- **Occupation**: [Job Information]

## Preferences
- **Communication Style**: Concise and direct
- **Information Format**: Prefers lists and tables
- **Reminders**: 1 hour before important events
- **Privacy Level**: High priority on privacy protection

## Common Tasks
- [ ] Schedule management and reminders
- [ ] Information search and organization
- [ ] Document creation and editing
- [ ] Study material collection
- [ ] Daily life reminders

## Important Notes
- Work hours: 9:00–18:00
- Rest hours: 22:00–8:00 (do not disturb unless urgent)
- Key contacts: [Contact information]
Enter fullscreen mode Exit fullscreen mode

MEMORY.md — Initial Memory 

# MEMORY.md — Personal Assistant Memory

## Creation Record
- **Created**: 2026-02-15
- **Created by**: New OpenClaw user
- **Purpose**: Personal daily task management

## User Preferences
- Communication style: Concise and efficient
- Information format: Structured presentation
- Work habits: To be learned

## Important Task Log
- [ ] Help user get familiar with OpenClaw
- [ ] Establish daily workflow
- [ ] Complete personal information profile

## Learning Notes
- OpenClaw basic concepts understood
- Agent configuration and deployment complete
- Tool usage needs hands-on practice
Enter fullscreen mode Exit fullscreen mode

🚀 Launch and Test the Agent

Step 1: Start the OpenClaw Gateway 

# Make sure you're in the correct workspace
cd ~/.openclaw/workspace-main

# Start the Gateway
openclaw gateway start

# Watch the startup logs
tail -f logs/gateway.log
Enter fullscreen mode Exit fullscreen mode

Expected Log Output:

[INFO] Gateway starting on port 18789
[INFO] Loading agent: personal-assistant
[INFO] Agent personal-assistant workspace: ./agents/personal-assistant
[INFO] Tools loaded for personal-assistant: read,write,exec,web_search...
[INFO] Gateway ready for connections
Enter fullscreen mode Exit fullscreen mode

Step 2: API Test 

# Test Agent response
curl -X POST http://localhost:18789/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "personal-assistant",
    "messages": [
      {
        "role": "user",
        "content": "Hello, please introduce yourself"
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

Expected Response: 

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "model": "personal-assistant",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Hello! 😊 I'm your personal assistant AI. I can help you with:\n\n📅 **Scheduling**: Arrange meetings, set reminders\n📝 **Information**: Search and organize documents\n💻 **File Management**: Create, edit, and manage files\n🔍 **Research**: Search the web and summarize findings\n\nI'll remember our conversations and your preferences to provide increasingly personalized service. How can I help you?"
      }
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

💬 Basic Conversation Tests

Test 1: Basic Interaction 

# Request
{
  "model": "personal-assistant",
  "messages": [
    {"role": "user", "content": "Help me create a work plan for today"}
  ]
}

# Expected: The Agent will ask about specifics, then help create a plan
Enter fullscreen mode Exit fullscreen mode

Test 2: Tool Usage 

# Request
{
  "model": "personal-assistant",
  "messages": [
    {"role": "user", "content": "Create a README.md file in the working directory"}
  ]
}

# Expected: The Agent will use the write tool to create the file
Enter fullscreen mode Exit fullscreen mode

Test 3: Information Search 

# Request
{
  "model": "personal-assistant",
  "messages": [
    {"role": "user", "content": "Search for today's weather"}
  ]
}

# Expected: The Agent will use the web_search tool to look up weather
Enter fullscreen mode Exit fullscreen mode

📱 Integrate with Telegram Bot (Optional)

Create a Telegram Bot

  1. Find @botfather: Search for @botfather in Telegram
  2. Create a new Bot: Send /newbot
  3. Set the name: e.g., "My Personal Assistant"
  4. Set the username: e.g., "my_personal_assistant_bot"
  5. Get the Token: Save the Bot Token

Configure Telegram Integration

Edit openclaw.json and add the Telegram configuration:

{
  "gateway": {
    "port": 18789,
    "bind": "loopback"
  },
  "agents": [
    {
      "id": "personal-assistant"
      // ... other config remains unchanged
    }
  ],
  "telegram": {
    "accounts": [
      {
        "name": "personal-assistant-bot",
        "botToken": "1234567890:ABCDEF...",  // Your Bot Token
        "binding": "personal-assistant"      // Bind to personal-assistant
      }
    ]
  },
  "auth": {
    "profiles": [
      {
        "id": "anthropic",
        "provider": "anthropic"
      }
    ]
  },
  "tools": {
    "allowlists": {
      "personal-assistant": [
        "read", "write", "exec", "web_search",
        "memory_search", "memory_get", "message",
        "sessions_list", "cron"
      ]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Restart and Test 

# Restart the Gateway to load the Telegram configuration
openclaw gateway restart

# Find your Bot in Telegram and send a message
# You should receive a reply from the Agent
Enter fullscreen mode Exit fullscreen mode

🛠️ Tool Usage Examples

File Operations 

# User: "Create a shopping list for me"
# Agent executes:
write("shopping-list.md", "# Shopping List\n\n- [ ] Bread\n- [ ] Milk\n- [ ] Eggs")
Enter fullscreen mode Exit fullscreen mode

Information Search 

# User: "What's the weather like in Tokyo today?"
# Agent executes:
web_search("Tokyo weather today")
# Then formats and returns the search results
Enter fullscreen mode Exit fullscreen mode

Memory Operations 

# User: "Remember that I like coffee"
# Agent executes:
memory_update("User preferences", "Beverages: Likes coffee")
Enter fullscreen mode Exit fullscreen mode

❗ Troubleshooting

Issue 1: Agent Fails to Start 

[ERROR] Failed to load agent personal-assistant: Invalid model configuration
Enter fullscreen mode Exit fullscreen mode

Solution:

  1. Check openclaw.json for syntax errors
  2. Verify API key configuration: openclaw auth list
  3. Test model connectivity: openclaw test anthropic

Issue 2: Tool Permission Error 

[ERROR] Tool 'web_search' not allowed for agent personal-assistant
Enter fullscreen mode Exit fullscreen mode

Solution:
Add the required tool to tools.allowlists:

"tools": {
  "allowlists": {
    "personal-assistant": ["read", "write", "exec", "web_search"]
  }
}
Enter fullscreen mode Exit fullscreen mode

Issue 3: Memory File Not Accessible 

[ERROR] Cannot read MEMORY.md: ENOENT
Enter fullscreen mode Exit fullscreen mode

Solution:

# Ensure the Agent workspace exists
mkdir -p agents/personal-assistant
cd agents/personal-assistant

# Create the required memory files
touch MEMORY.md SOUL.md USER.md
Enter fullscreen mode Exit fullscreen mode

Issue 4: Telegram Bot Not Responding 

[ERROR] Telegram polling failed: 401 Unauthorized
Enter fullscreen mode Exit fullscreen mode

Solution:

  1. Check that the Bot Token is correct
  2. Confirm the Bot is activated
  3. Test the Token: curl https://api.telegram.org/bot<TOKEN>/getMe

🎯 Agent Optimization Tips

Performance Optimization 

{
  "id": "personal-assistant",
  "model": "anthropic/claude-sonnet-4-20250514",
  "maxConcurrency": 2,           // Limit concurrency
  "timeout": 30000,              // 30-second timeout
  "contextPruning": {            // Context pruning
    "enabled": true,
    "maxTokens": 50000,
    "strategy": "sliding-window"
  },
  "caching": {                   // Enable caching
    "enabled": true,
    "maxEntries": 1000
  }
}
Enter fullscreen mode Exit fullscreen mode

Security Configuration 

{
  "security": {
    "sandbox": true,             // Enable sandbox
    "allowedPaths": [            // Restrict file access
      "./agents/personal-assistant/*",
      "./shared/*"
    ],
    "deniedCommands": [          // Denied commands
      "rm -rf",
      "sudo",
      "passwd"
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

📊 Monitoring and Logging

Check Agent Status 

# View all Agent statuses
openclaw status

# View a specific Agent's status
openclaw status personal-assistant

# View real-time logs
tail -f logs/agents/personal-assistant.log
Enter fullscreen mode Exit fullscreen mode

Performance Monitoring 

# View system resource usage
openclaw metrics

# View Agent statistics
openclaw stats personal-assistant
Enter fullscreen mode Exit fullscreen mode

✅ Chapter Summary

After this chapter, you should have:

  • [x] Understood the Agent concept and configuration structure
  • [x] Successfully created your first personal assistant Agent
  • [x] Configured Agent identity files (SOUL.md, USER.md, MEMORY.md)
  • [x] Completed basic conversation tests
  • [x] Mastered tool usage and permission configuration
  • [x] Learned about Telegram Bot integration
  • [x] Known solutions for common issues

🚀 Next Steps

Congratulations! You now have a working AI Agent. Next, you can:

Next Chapter: Tools and Skills →

📝 Practice Exercises

  1. Customize: Modify SOUL.md to create Agents with different personalities
  2. Expand Skills: Add new tool permissions to your Agent
  3. Multi-Channel Test: Configure a Telegram Bot and test interactions
  4. Memory Features: Have the Agent remember your preferences and habits
  5. Error Handling: Deliberately introduce bad configurations and practice troubleshooting

Ready to explore more advanced features? 🎯

📌 This article is written by the AI team at TechsFree

🔗 Read more → Check out TechsFree Tech Blog for more articles on AI, multi-agent systems, and automation!

🌐 Website | 📖 Tech Blog | 💼 Our Services

Top comments (0)