API Documentation

Quick Start: Build Your First Skill

Get started with OpenClaw SDK in just 4 steps:

1. Install SDK

npm install @clawdbot/sdk

2. Initialize Skill Project

npx clawdbot-skill init my-skill

3. Implement Skill Logic

// Edit skills/my-skill/index.ts
import { Skill } from '@clawdbot/sdk'

export default class MySkill extends Skill {
  async execute(params: any) {
    // Your skill logic here
    return { success: true }
  }
}

4. Test and Install

# Test locally
clawdbot skills test ./my-skill

# Install to OpenClaw
clawdbot skills install ./my-skill

Authentication

API Key Authentication

Include your API key in the request header:

curl -X GET https://your-clawdbot.local:3000/api/v1/status \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

OAuth 2.0

Use OAuth for third-party integrations:

# Generate OAuth token
clawdbot auth create --client-id YOUR_CLIENT_ID

# Use token in requests
curl -X POST https://your-clawdbot.local:3000/api/v1/assistant/chat \
  -H "Authorization: Bearer YOUR_OAUTH_TOKEN" \
  -d '{"message": "Hello, OpenClaw!"}'

REST API

Interact with OpenClaw via RESTful endpoints.

GET /api/v1/status

Get OpenClaw service status and health information.

Response:

{
  "status": "running",
  "version": "1.0.0",
  "uptime": 86400,
  "health": "healthy",
  "skills": {
    "installed": 12,
    "active": 8
  }
}

POST /api/v1/skills/{skill}/execute

Execute a specific skill with parameters.

Response:

{
  "success": true,
  "result": {
    "action": "voice_command",
    "response": "Lights turned off",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

GET /api/v1/skills

List all installed skills.

Response:

{
  "skills": [
    {
      "name": "voice-assistant",
      "version": "2.1.0",
      "status": "active",
      "enabled": true
    }
  ]
}

POST /api/v1/assistant/chat

Send a message to the AI assistant.

Response:

{
  "response": "I can help you with that...",
  "model": "claude-3.5-sonnet",
  "tokens_used": 150,
  "timestamp": "2025-01-15T10:30:00Z"
}

Webhooks

Receive real-time notifications from OpenClaw.

skill.activated

Fired when a skill is activated.

Payload:

{
  "event": "skill.activated",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "skill": "voice-assistant",
    "trigger": "wake_word",
    "confidence": 0.95
  }
}

automation.completed

Fired when an automation rule completes.

Payload:

{
  "event": "automation.completed",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "automation": "morning-routine",
    "status": "success",
    "duration_ms": 1250
  }
}

system.alert

Fired for system alerts and warnings.

Payload:

{
  "event": "system.alert",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "severity": "warning",
    "message": "High memory usage detected",
    "memory_percent": 85
  }
}

Skill Development

Build custom skills for OpenClaw.

Basic Skill Structure

// skills/custom-timer/index.ts
import { Skill } from '@clawdbot/sdk'

export default class TimerSkill extends Skill {
  constructor() {
    super({
      name: 'custom-timer',
      version: '1.0.0',
      description: 'Create custom timers',
    })
  }

  async execute(params: { duration: number }) {
    const { duration } = params

    // Create timer
    await this.timers.create(duration, async () => {
      await this.notify('Timer complete!')
    })

    return {
      success: true,
      message: `Timer set for ${duration} seconds`,
    }
  }
}

Skill with Configuration

// skills/weather-alert/index.ts
import { Skill, SkillConfig } from '@clawdbot/sdk'

const config: SkillConfig = {
  name: 'weather-alert',
  version: '1.0.0',
  description: 'Weather monitoring and alerts',
  dependencies: ['weather-api'],
  permissions: ['location', 'notifications'],
}

export default class WeatherAlertSkill extends Skill {
  constructor() {
    super(config)
  }

  async onEnable() {
    // Set up weather monitoring
    this.schedule.every('1h', () => this.checkWeather())
  }

  async checkWeather() {
    const weather = await this.api.weather.getCurrent()
    if (weather.severity === 'severe') {
      await this.notifications.send({
        title: 'Severe Weather Alert',
        body: weather.description,
        urgency: 'high',
      })
    }
  }
}

Registering Skill Commands

// skills/home-automation/index.ts
import { Skill, Command } from '@clawdbot/sdk'

export default class HomeAutomationSkill extends Skill {
  constructor() {
    super({
      name: 'home-automation',
      version: '1.0.0',
      description: 'Smart home controls',
    })
  }

  registerCommands(): Command[] {
    return [
      {
        name: 'lights.on',
        handler: async (args) => {
          await this.api.hue.turnOn(args.room)
          return `Lights on in ${args.room}`
        },
      },
      {
        name: 'thermostat.set',
        handler: async (args) => {
          await this.api.thermostat.setTemperature(args.temp)
          return `Temperature set to ${args.temp}°F`
        },
      },
    ]
  }
}

SDK Reference

Essential methods available in the OpenClaw SDK.

Skill Base Class

Extend the Skill base class to create custom skills. Override methods like execute(), onEnable(), and onDisable() to implement behavior.

API Access

Access external APIs through this.api. Built-in clients for weather, calendar, home automation, and more. Add custom API clients easily.

Notifications

Send notifications using this.notify() or this.notifications.send(). Support for different urgency levels and custom payloads.

Scheduling

Schedule tasks with this.schedule.every(), this.schedule.cron(), or this.schedule.once(). Perfect for recurring jobs.

Development Best Practices

• Always handle errors gracefully and return meaningful error messages
• Use TypeScript for type safety and better IDE support
• Write unit tests for your skills using the SDK testing utilities
• Document your skill's configuration options and required permissions
• Use logging for debugging: this.logger.info()

Ready to Build!

You have everything you need to start building OpenClaw skills. Check out the Skills Library for examples, or visit GitHub Examples for complete skill projects.

Continue Exploring

Deepen your understanding of OpenClaw development and deployment.

• CLI Reference - Command-line reference
• Browse Skills - Skills library
• SDK on GitHub - SDK documentation
• Get Help - Troubleshooting