OpenClaw Assistant Setup

The OpenClaw Assistant is the AI agent that processes your messages and generates responses. This guide covers setting up and configuring the assistant.

What is the OpenClaw Assistant?

The OpenClaw Assistant is powered by Pi, a coding agent designed for autonomous task execution. Unlike simple chatbots, Pi can:

Write and execute code
Browse the web for information
Manipulate files and directories
Run terminal commands
Integrate with external APIs

Agent Architecture

User Message → Gateway → Pi Agent → Tool Execution → Response

The agent operates in RPC mode, communicating with the Gateway via secure local connections.

Prerequisites

Before setting up the assistant:

OpenClaw Gateway running - See Getting Started
Pi agent installed - Usually bundled with OpenClaw
API keys - For AI models (Claude, GPT-4, etc.)

Installation

Method 1: Bundled Pi (Recommended)

Pi is included with OpenClaw by default:

# Verify Pi is available
openclaw agent status

# Test Pi connection
openclaw agent test

Method 2: Separate Pi Installation

For custom Pi setups:

# Install Pi separately
npm install -g @badlogic/pi

# Configure OpenClaw to use external Pi
openclaw config set agents.default.rpc.host 127.0.0.1
openclaw config set agents.default.rpc.port 8080

Configuration

Basic Agent Setup

Edit ~/.openclaw/openclaw.json:

{
  agents: {
    default: {
      type: "pi",
      rpc: {
        host: "127.0.0.1",
        port: 8080,
        timeout: 30000
      },
      model: "claude-3.5-sonnet",
      maxTokens: 4096,
      temperature: 0.7
    }
  }
}

Model Configuration

Claude (Anthropic)

{
  agents: {
    default: {
      model: "claude-3.5-sonnet",
      anthropic: {
        apiKey: "your-anthropic-api-key",
        maxTokens: 4096
      }
    }
  }
}

OpenAI GPT

{
  agents: {
    default: {
      model: "gpt-4",
      openai: {
        apiKey: "your-openai-api-key",
        baseURL: "https://api.openai.com/v1",
        maxTokens: 4096
      }
    }
  }
}

Local Models (Ollama)

{
  agents: {
    default: {
      model: "llama3.1",
      ollama: {
        host: "127.0.0.1",
        port: 11434,
        model: "llama3.1:8b"
      }
    }
  }
}

Agent Capabilities

File System Operations

Pi can read, write, and manipulate files:

# User: "Create a new Python script that calculates fibonacci"
# Pi will:
# 1. Create fibonacci.py
# 2. Write the implementation
# 3. Test the script
# 4. Report results

Web Browsing

Pi can browse the web for information:

# User: "Find the latest React documentation"
# Pi will:
# 1. Open browser
# 2. Navigate to react.dev
# 3. Extract relevant information
# 4. Summarize findings

Terminal Commands

Pi can execute terminal commands:

# User: "Check system disk usage"
# Pi will:
# 1. Run `df -h`
# 2. Parse output
# 3. Present readable summary

API Integration

Pi can interact with external APIs:

# User: "Post a message to our Slack channel"
# Pi will:
# 1. Use Slack API
# 2. Authenticate with stored token
# 3. Send the message
# 4. Confirm delivery

Security Considerations

Sandboxing

For security, consider running Pi in a sandboxed environment:

# Docker sandbox (recommended)
docker run -it --rm \
  -v $(pwd):/workspace \
  --network=none \
  openclaw/pi-sandbox

# Or use OpenClaw's built-in sandboxing
openclaw config set agents.default.sandbox.enabled true

Permission Controls

Restrict what the agent can access:

{
  agents: {
    default: {
      permissions: {
        fileSystem: {
          allowedPaths: ["/workspace", "/tmp"],
          deniedPaths: ["/etc", "/usr/bin"]
        },
        network: {
          allowedDomains: ["api.github.com", "docs.example.com"],
          denyInternet: false
        },
        commands: {
          allowed: ["python", "node", "git"],
          denied: ["rm", "sudo", "chmod"]
        }
      }
    }
  }
}

Multi-Agent Setup

OpenClaw supports multiple agents for different tasks:

{
  agents: {
    coding: {
      type: "pi",
      model: "claude-3.5-sonnet",
      specialization: "coding"
    },
    research: {
      type: "pi",
      model: "gpt-4",
      specialization: "research"
    },
    chat: {
      type: "pi",
      model: "claude-3-haiku",
      specialization: "conversation"
    }
  },
  routing: {
    default: "chat",
    code: "coding",
    research: "research"
  }
}

Monitoring and Logging

Agent Logs

# View agent activity
openclaw agent logs

# Follow logs in real-time
openclaw agent logs --follow

# Filter by session
openclaw agent logs --session user123

Performance Metrics

# Check agent performance
openclaw agent stats

# Response times, token usage, error rates
openclaw agent metrics

Troubleshooting

Common Issues

Agent not responding

# Check agent status
openclaw agent status

# Restart agent
openclaw agent restart

# Check RPC connection
openclaw agent test

Model errors

# Verify API keys
openclaw config show agents.default.anthropic.apiKey

# Test model connection
openclaw agent test --model claude-3.5-sonnet

Permission denied

# Check agent permissions
openclaw config show agents.default.permissions

# Reset permissions to defaults
openclaw agent permissions reset

Debug Mode

Enable detailed logging for troubleshooting:

# Enable debug mode
openclaw config set logging.level debug

# Run agent with debug output
openclaw agent --debug

Advanced Configuration

Custom System Prompts

{
  agents: {
    default: {
      systemPrompt: "You are a helpful coding assistant. Always provide working code examples.",
      temperature: 0.3,
      maxTokens: 8192
    }
  }
}

Tool Configuration

{
  agents: {
    default: {
      tools: {
        fileSystem: true,
        webBrowser: true,
        terminal: true,
        api: {
          enabled: true,
          timeout: 10000
        }
      }
    }
  }
}

Memory and Context

{
  agents: {
    default: {
      memory: {
        maxContextLength: 10000,
        retainHistory: true,
        summaryThreshold: 8000
      }
    }
  }
}

Best Practices

Start with restrictive permissions - Gradually expand as needed
Use sandboxing - Especially for untrusted code execution
Monitor token usage - Set limits to control costs
Regular backups - Backup configuration and important data
Update regularly - Keep Pi and OpenClaw updated

Next Steps

Configure specific channels - Set up messaging platforms
Explore routing rules - Advanced agent routing
Set up monitoring - Track agent performance
Security hardening - Production security setup

Your OpenClaw Assistant is now ready to help you with coding, research, and automation tasks! 🤖