Tool Categories

OpenClaw provides three primary categories of built-in tools, each enabling different types of real-world interactions:

Shell Command Execution

Basic Usage

// Tool definition
{
  name: 'shell_exec',
  description: 'Execute a shell command',
  parameters: {
    command: { type: 'string', required: true },
    cwd: { type: 'string', default: './workspace' },
    timeout: { type: 'number', default: 30000 }
  }
}

Safety Features

// Command filtering
const dangerousPatterns = [
  /rm\s+-rf\s+\//, // rm -rf /
  /:(){ :|:& };:/,    // Fork bomb
  /dd\s+if=/,        // Disk operations
];

function validateCommand(cmd: string): boolean {
  return !dangerousPatterns.some(p => p.test(cmd));
}

Example Interactions

User: "Show me the disk usage"
Agent: Executing: df -h
Result:
Filesystem      Size  Used  Avail  Use%
/dev/sda1       100G   45G   55G   45%

User: "Find all JavaScript files modified today"
Agent: Executing: find . -name "*.js" -mtime 0
Result:
./src/app.js
./src/utils/helper.js

File System Operations

Available Operations

// File tools
const fileTools = {
  readFile: {
    params: { path: 'string' },
    returns: { content: 'string', encoding: 'string' }
  },
  writeFile: {
    params: { path: 'string', content: 'string' },
    returns: { success: 'boolean', bytesWritten: 'number' }
  },
  listDirectory: {
    params: { path: 'string', recursive: 'boolean' },
    returns: { files: 'FileInfo[]' }
  },
  moveFile: {
    params: { source: 'string', destination: 'string' },
    returns: { success: 'boolean' }
  },
  deleteFile: {
    params: { path: 'string', confirm: 'boolean' },
    returns: { success: 'boolean' }
  }
};

Path Validation

class FileSystem {
  private allowedRoots = ['/workspace', '/tmp/openclaw'];
  
  validatePath(requestedPath: string): boolean {
    const resolved = path.resolve(requestedPath);
    return this.allowedRoots.some(root => 
      resolved.startsWith(root)
    );
  }
}

Example Workflow

User: "Create a project structure for a Node.js app"

Agent Actions:
1. mkdir ./project
2. mkdir ./project/src
3. mkdir ./project/tests
4. writeFile ./project/package.json { ... }
5. writeFile ./project/src/index.js "..."
6. writeFile ./project/README.md "..."

Result: Created 6 files in ./project/

Browser Automation

Browser Tools

const browserTools = {
  navigate: {
    params: { url: 'string' },
    description: 'Navigate to a URL'
  },
  screenshot: {
    params: { selector?: 'string', fullPage: 'boolean' },
    description: 'Capture page screenshot'
  },
  click: {
    params: { selector: 'string' },
    description: 'Click an element'
  },
  type: {
    params: { selector: 'string', text: 'string' },
    description: 'Type text into an input'
  },
  extract: {
    params: { selector: 'string', attribute?: 'string' },
    description: 'Extract text or attribute from elements'
  }
};

Example: Web Scraping

User: "Get the top 5 headlines from Hacker News"

Agent Execution:
1. navigate('https://news.ycombinator.com')
2. extract('.titleline > a', { limit: 5 })

Result:
1. "New AI Framework Released" (points: 342)
2. "Tech Industry Layoffs Continue" (points: 289)
3. "Open Source Milestone" (points: 256)
...

Headless Configuration

// Browser configuration
{
  browser: {
    headless: true,
    viewport: { width: 1280, height: 720 },
    userAgent: 'OpenClaw/1.0',
    timeout: 30000,
    blockedResources: ['image', 'font', 'media']
  }
}

Creating Custom Tools

Tool Definition

const customTool = {
  name: 'weather_check',
  description: 'Get current weather for a location',
  parameters: {
    type: 'object',
    properties: {
      location: {
        type: 'string',
        description: 'City name or coordinates'
      },
      units: {
        type: 'string',
        enum: ['celsius', 'fahrenheit'],
        default: 'celsius'
      }
    },
    required: ['location']
  },
  handler: async ({ location, units }) => {
    const data = await weatherAPI.get(location, units);
    return {
      temperature: data.temp,
      conditions: data.conditions,
      humidity: data.humidity
    };
  }
};

Conclusion

OpenClaw's tool system provides powerful capabilities for real-world interaction. By understanding how shell, file, and browser tools work, you can build agents that effectively automate complex tasks while maintaining security and control.