OpenClaw Integration

Overview

OpenClaw is a specialized HTTP adapter for integrating with OpenClaw remote agent platforms. It provides webhook-based invocation with Paperclip-specific payload formatting and session management. OpenClaw adapters are ideal for:

Remote agent execution on OpenClaw infrastructure
Distributed teams of agents across multiple environments
Cloud-hosted agents separate from Paperclip server

OpenClaw uses the same HTTP adapter foundation but includes specialized payload formatting and error handling for OpenClaw endpoints.

Configuration Schema

{
  "adapterType": "openclaw",
  "adapterConfig": {
    "url": "https://openclaw.example.com/api/webhook/invoke",
    "method": "POST",
    "headers": {
      "Content-Type": "application/json"
    },
    "webhookAuthHeader": "Bearer sk-openclaw-abc123",
    "payloadTemplate": {
      "environment": "production",
      "priority": "high"
    },
    "timeoutSec": 30
  }
}

Configuration Fields

Field	Type	Required	Description
`url`	string	Yes	OpenClaw webhook endpoint URL
`method`	string	No	HTTP method (default: `POST`)
`headers`	object	No	Custom HTTP headers
`webhookAuthHeader`	string	No	Authorization header value (recommended)
`payloadTemplate`	object	No	Additional fields merged into payload
`timeoutSec`	number	No	Request timeout in seconds (default: 30)

Request Payload

OpenClaw adapters send a nested payload structure:

{
  "paperclip": {
    "runId": "run_abc123",
    "agentId": "agent_xyz789",
    "companyId": "company_456",
    "taskId": "task_123",
    "issueId": "task_123",
    "wakeReason": "task_assigned",
    "wakeCommentId": null,
    "approvalId": null,
    "approvalStatus": null,
    "issueIds": ["task_123", "task_456"],
    "context": {
      "taskId": "task_123",
      "wakeReason": "task_assigned",
      "paperclipWorkspace": {
        "cwd": "/workspace",
        "source": "manual"
      }
    }
  },
  "environment": "production",
  "priority": "high"
}

Key Differences from Generic HTTP Adapter

Nested structure: Paperclip fields are under paperclip key
Context duplication: Full context object is included alongside flattened fields
Custom template merge: payloadTemplate fields are merged at root level

Authentication

OpenClaw adapters support authentication via:

webhookAuthHeader
Custom Headers

Simplest method - set the Authorization header directly:

{
  "webhookAuthHeader": "Bearer ${secrets.openclaw_token}"
}

This is automatically added as the Authorization header if not present in headers.

For non-standard auth, use headers directly:

{
  "headers": {
    "X-OpenClaw-API-Key": "${secrets.openclaw_api_key}",
    "X-Signature": "hmac-sha256-signature"
  }
}

Always use secret references (${secrets.name}) instead of hardcoding tokens in configuration.

Example Configurations

Basic OpenClaw Agent

{
  "name": "Remote Engineer",
  "role": "software_engineer",
  "adapterType": "openclaw",
  "adapterConfig": {
    "url": "https://openclaw.mycompany.com/webhook/agent-123",
    "webhookAuthHeader": "Bearer ${secrets.openclaw_token}",
    "timeoutSec": 60
  },
  "contextMode": "thin",
  "budgetMonthlyCents": 5000
}

OpenClaw with Custom Payload

{
  "name": "Data Scientist",
  "role": "data_scientist",
  "adapterType": "openclaw",
  "adapterConfig": {
    "url": "https://agents.openclaw.io/v2/invoke",
    "webhookAuthHeader": "Bearer ${secrets.openclaw_api_key}",
    "payloadTemplate": {
      "agentVersion": "2.1.0",
      "resourceLimits": {
        "memory": "4GB",
        "cpu": "2"
      },
      "environment": "production"
    },
    "timeoutSec": 120
  },
  "contextMode": "fat"
}

Multi-Region OpenClaw Setup

[
  {
    "name": "US Engineer",
    "role": "engineer",
    "adapterType": "openclaw",
    "adapterConfig": {
      "url": "https://us-east.openclaw.example.com/webhook",
      "webhookAuthHeader": "Bearer ${secrets.openclaw_us_token}",
      "payloadTemplate": {
        "region": "us-east-1"
      }
    }
  },
  {
    "name": "EU Engineer",
    "role": "engineer",
    "adapterType": "openclaw",
    "adapterConfig": {
      "url": "https://eu-west.openclaw.example.com/webhook",
      "webhookAuthHeader": "Bearer ${secrets.openclaw_eu_token}",
      "payloadTemplate": {
        "region": "eu-west-1"
      }
    }
  }
]

Response Handling

OpenClaw endpoints should return standard HTTP responses:

Success (Synchronous)

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "completed",
  "sessionId": "openclaw_session_xyz",
  "result": "Task completed successfully",
  "usage": {
    "inputTokens": 1234,
    "outputTokens": 567
  }
}

Accepted (Asynchronous)

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "status": "accepted",
  "executionId": "openclaw_exec_123"
}

For asynchronous execution, the OpenClaw platform should callback to Paperclip when finished (see HTTP Adapter callbacks).

Error Response

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "error": "unknown_session",
  "message": "Session openclaw_session_xyz not found"
}

Paperclip detects unknown_session errors and clears the saved session automatically.

Session Management

OpenClaw supports session continuity across invocations:

First invocation: OpenClaw returns sessionId in response
Subsequent invocations: Paperclip includes sessionId in wake context
Session invalidation: OpenClaw returns unknown_session error
Auto-recovery: Paperclip clears session and retries with fresh context

Session Response

{
  "status": "completed",
  "sessionId": "openclaw_session_abc123",
  "result": "Task completed"
}

Next Invocation

Paperclip automatically includes session in context:

{
  "paperclip": {
    "runId": "run_def456",
    "agentId": "agent_xyz789",
    "context": {
      "sessionId": "openclaw_session_abc123"
    }
  }
}

Error Codes

OpenClaw adapter recognizes these error codes:

Error Code	Description	Paperclip Action
`openclaw_url_missing`	No URL configured	Mark run as failed
`openclaw_http_error`	Non-2xx HTTP response	Mark run as failed, log response
`openclaw_request_failed`	Connection/network error	Mark run as failed
`timeout`	Request exceeded `timeoutSec`	Mark run as timed out
`unknown_session`	Session no longer exists	Clear session, retry

Testing OpenClaw Integration

Test your OpenClaw webhook:

curl -X POST http://localhost:3100/api/agents/:agentId/heartbeat/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "wakeReason": "manual",
    "taskId": "task_123"
  }'

Check the heartbeat run result:

curl http://localhost:3100/api/heartbeat-runs/:runId

Look for:

exitCode: 0 for success
errorCode: "openclaw_http_error" for failures
resultJson.response for OpenClaw response body

Monitoring and Debugging

View Recent Heartbeat Runs

curl http://localhost:3100/api/companies/:companyId/heartbeat-runs?agentId=:agentId&limit=10

Check Agent Session State

curl http://localhost:3100/api/agents/:agentId

Look for runtime.sessionId and runtime.sessionParams.

View Logs

Heartbeat run logs include OpenClaw request/response:

[openclaw] invoking POST https://openclaw.example.com/webhook
[openclaw] response (200) {"status":"completed","sessionId":"..."}

Access via:

curl http://localhost:3100/api/heartbeat-runs/:runId/logs

Best Practices

Use webhookAuthHeader for simple auth

Prefer webhookAuthHeader over manual header configuration:

{
  "webhookAuthHeader": "Bearer ${secrets.openclaw_token}"
}

This is automatically added to the Authorization header.

Set appropriate timeouts

Match timeoutSec to your OpenClaw endpoint’s expected response time:

{
  "timeoutSec": 60  // 60 seconds for typical OpenClaw operations
}

Include region in payloadTemplate

For multi-region setups, include region metadata:

{
  "payloadTemplate": {
    "region": "us-east-1",
    "environment": "production"
  }
}

Monitor session continuity

Check that sessions persist across invocations:

# Should show same sessionId across runs
curl http://localhost:3100/api/agents/:agentId | jq '.runtime.sessionId'

When NOT to Use OpenClaw

Don’t use OpenClaw adapter if:

You need local CLI execution → Use process adapters
Your endpoint is not reachable from Paperclip server → Fix networking or use VPN
You need generic HTTP webhook → Use HTTP adapter instead
You want synchronous subprocess → Use claude_local or codex_local

Troubleshooting

Webhook URL not reachable

Test connectivity from Paperclip server:

curl -v https://openclaw.example.com/webhook

Check for:

DNS resolution failures
Firewall/network blocking
SSL/TLS certificate errors

Authentication failures

Verify the auth token is valid:

curl -H "Authorization: Bearer your-token" https://openclaw.example.com/webhook

Ensure the secret reference is correct:

paperclipai secrets get openclaw_token

Session not persisting

Check that OpenClaw returns sessionId in response:

{
  "sessionId": "openclaw_session_abc123",
  "status": "completed"
}

Verify Paperclip saves it:

curl http://localhost:3100/api/agents/:agentId | jq '.runtime.sessionId'

Unknown session errors

OpenClaw should return:

{
  "error": "unknown_session",
  "message": "Session not found"
}

Paperclip automatically clears the session and retries.

Next Steps

HTTP Adapter

Learn about generic HTTP webhook adapters

Custom Adapters

Build your own adapter for custom platforms

Get Started

Core Concepts

Guides

Agent Integration

Deployment

OpenClaw Integration

Overview

Configuration Schema

Configuration Fields

Request Payload

Key Differences from Generic HTTP Adapter

Authentication

Example Configurations

Basic OpenClaw Agent

OpenClaw with Custom Payload

Multi-Region OpenClaw Setup

Response Handling

Success (Synchronous)

Accepted (Asynchronous)

Error Response

Session Management

Session Response

Next Invocation

Error Codes

Testing OpenClaw Integration

Monitoring and Debugging

View Recent Heartbeat Runs

Check Agent Session State

View Logs

Best Practices

When NOT to Use OpenClaw

Troubleshooting

Webhook URL not reachable

Authentication failures

Session not persisting

Unknown session errors

Next Steps

HTTP Adapter

Custom Adapters

Get Started

Core Concepts

Guides

Agent Integration

Deployment

​Overview

​Configuration Schema

​Configuration Fields

​Request Payload

​Key Differences from Generic HTTP Adapter

​Authentication

​Example Configurations

​Basic OpenClaw Agent

​OpenClaw with Custom Payload

​Multi-Region OpenClaw Setup

​Response Handling

​Success (Synchronous)

​Accepted (Asynchronous)

​Error Response

​Session Management

​Session Response

​Next Invocation

​Error Codes

​Testing OpenClaw Integration

​Monitoring and Debugging

​View Recent Heartbeat Runs

​Check Agent Session State

​View Logs

​Best Practices

​When NOT to Use OpenClaw

​Troubleshooting

​Webhook URL not reachable

​Authentication failures

​Session not persisting

​Unknown session errors

​Next Steps

HTTP Adapter

Custom Adapters

Overview

Configuration Schema

Configuration Fields

Request Payload

Key Differences from Generic HTTP Adapter

Authentication

Example Configurations

Basic OpenClaw Agent

OpenClaw with Custom Payload

Multi-Region OpenClaw Setup

Response Handling

Success (Synchronous)

Accepted (Asynchronous)

Error Response

Session Management

Session Response

Next Invocation

Error Codes

Testing OpenClaw Integration

Monitoring and Debugging

View Recent Heartbeat Runs

Check Agent Session State

View Logs

Best Practices

When NOT to Use OpenClaw

Troubleshooting

Webhook URL not reachable

Authentication failures

Session not persisting

Unknown session errors

Next Steps