# How the OpenClaw Gateway Integration Connects External Agents to Paperclip: A Complete Technical Guide

> Learn how the OpenClaw gateway integration securely connects external agents to Paperclip using WebSockets, tokens, and standardized join requests. Explore the technical guide for Paperclip AI.

- Repository: [Paperclip/paperclip](https://github.com/paperclipai/paperclip)
- Tags: how-to-guide
- Published: 2026-08-16

---

**The OpenClaw gateway integration connects external agents to Paperclip through a secure WebSocket handshake that uses a one-time token, gateway URL validation, and a standardized join request process.**

Paperclip's OpenClaw gateway enables any WebSocket-based external runtime to operate as a first-class Paperclip agent. This integration bridges external AI systems with Paperclip's native agent infrastructure through a carefully designed authentication and connection protocol.

## Overview of the OpenClaw Gateway Architecture

The integration follows a three-phase pattern: **invite generation**, **credential validation**, and **persistent connection establishment**. Each phase includes server-side security checks and explicit error handling implemented across multiple source files in the Paperclip repository.

According to the paperclipai/paperclip source code, the gateway treats external OpenClaw runtimes identically to built-in agents once the handshake completes—including heartbeat management, skill execution, and API access.

## Phase 1: Generating the OpenClaw Invite Prompt

The integration begins when an administrator requests an invitation through the dedicated API endpoint.

### Invite Generation Endpoint

```

POST /api/companies/:companyId/openclaw/invite-prompt

```

This endpoint is defined in [`server/src/routes/openapi.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/openapi.ts) alongside its request schema `createOpenClawInvitePromptSchema` (lines 159-4236). The handler generates a cryptographically secure, short-lived token and packages it with Paperclip's base URL.

The response provides everything needed to configure an external OpenClaw instance:

```json
{
  "invitePrompt": "Copy-paste this into OpenClaw:",
  "gatewayUrl": "ws://paperclip-host:3100/api/agents/join",
  "token": "a1b2c3d4e5f6789012345678"
}

```

The `gatewayUrl` points directly to Paperclip's agent join API. The `token` is single-use and expires after a configurable timeout, preventing replay attacks.

## Phase 2: UI Adapter Configuration

Paperclip provides a dedicated UI adapter that standardizes how users input gateway credentials.

### Adapter Implementation Files

- **Main adapter**: [`ui/src/adapters/openclaw-gateway/index.ts`](https://github.com/paperclipai/paperclip/blob/main/ui/src/adapters/openclaw-gateway/index.ts)
- **Configuration UI**: [`ui/src/adapters/openclaw-gateway/config-fields.tsx`](https://github.com/paperclipai/paperclip/blob/main/ui/src/adapters/openclaw-gateway/config-fields.tsx)

The adapter enforces two required fields:

| Field | Validation | Purpose |
|-------|-----------|---------|
| `url` | Must use `ws://` or `wss://` protocol | WebSocket endpoint for the join API |
| `headers.x-openclaw-token` | Minimum length, single-use verification | Authentication credential from invite prompt |

This UI abstraction ensures consistent configuration across different deployment environments and reduces user error when connecting external systems.

## Phase 3: Server-Side Validation of Gateway Payloads

All inbound join requests route through [`server/src/routes/access.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/access.ts), where the function `buildJoinDefaultsPayloadForAccept` (lines 529-560) performs rigorous validation.

### Validation Checks in buildJoinDefaultsPayloadForAccept

The implementation enforces four specific conditions with dedicated error codes:

1. **URL presence**: Returns `openclaw_gateway_url_missing` if no URL provided
2. **Protocol restriction**: Returns `openclaw_gateway_url_protocol` for non-WebSocket schemes
3. **Token header presence**: Returns `openclaw_gateway_auth_header_missing` if `x-openclaw-token` absent
4. **Token length**: Returns `openclaw_gateway_auth_header_too_short` for insufficient token entropy

Additional reachability validation occurs in lines 858-877, which verifies the gateway URL against Paperclip's allowed hostname list via `npx paperclipai allowed-hostname` checks, returning `openclaw_gateway_url_invalid` on failure.

Upon successful validation, the server constructs a **defaults payload** containing the normalized URL and headers, which becomes part of the agent's permanent join record.

## Phase 4: Processing the Join Request

When the OpenClaw runtime initiates connection, it transmits a structured join request to `POST /api/agents/join`:

```json
{
  "adapterType": "openclaw_gateway",
  "agentDefaultsPayload": {
    "url": "ws://paperclip-host:3100/api/agents/join",
    "headers": {
      "x-openclaw-token": "a1b2c3d4e5f6789012345678"
    }
  },
  "agentName": "Production OpenClaw Agent",
  "capabilities": "OpenClaw gateway agent"
}

```

The same `buildJoinDefaultsPayloadForAccept` routine normalizes this payload. The server then:

- Consumes and invalidates the one-time token
- Associates the gateway URL with the agent record for heartbeat routing
- Creates the agent with `openclaw_gateway` as its adapter type

## Post-Join Agent Operation

Once validated, OpenClaw gateway agents receive full Paperclip agent privileges with runtime-specific adjustments.

### Heartbeat Management

[`server/src/services/heartbeat-stop-metadata.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/services/heartbeat-stop-metadata.ts) (line 43) assigns OpenClaw gateway agents a **120-second timeout**—longer than typical native agents to accommodate network variability in external WebSocket connections.

### Built-In Agent Integration

[`server/src/services/built-in-agents.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/services/built-in-agents.ts) (line 705) recognizes `openclaw_gateway` as a valid built-in adapter type, enabling command routing through the standard agent execution pipeline.

### Persistent WebSocket Behavior

All subsequent communication maintains the original WebSocket connection, providing low-latency bidirectional messaging identical to native Paperclip agents. The gateway URL stored during join becomes the routing target for server-initiated messages.

## Security Model

The OpenClaw gateway integration implements defense in depth across multiple layers:

- **Token generation**: Server-side cryptographically random tokens, never client-generated
- **Token lifecycle**: Single-use with explicit expiration, no persistence post-handshake
- **Transport security**: Mandatory `wss://` for production deployments
- **Hostname allowlisting**: Administrative control over reachable gateway endpoints
- **Header validation**: Strict `x-openclaw-token` presence and format verification

## End-to-End CLI Example

Complete workflow demonstrating the OpenClaw gateway integration:

```bash

# Step 1: Generate invite as company administrator

curl -X POST "http://localhost:3100/api/companies/123/openclaw/invite-prompt" \
  -H "Authorization: Bearer $CEO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agentMessage":"Connect production OpenClaw runtime"}'

# Response provides gatewayUrl and token for Step 2

# Step 2: Configure OpenClaw runtime using provided credentials

# (Typically via OpenClaw's native configuration interface)

# Step 3: Automatic join when OpenClaw initiates WebSocket connection

# No manual API call required—OpenClaw uses gatewayUrl and token directly

# Step 4: Verify agent registration

curl "http://localhost:3100/api/agents" \
  -H "Authorization: Bearer $ADMIN_TOKEN" | jq '.[] | select(.adapterType=="openclaw_gateway")'

```

## Summary

- The **OpenClaw gateway integration** bridges external WebSocket agents into Paperclip through a standardized four-phase handshake
- **Invite generation** in [`server/src/routes/openapi.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/openapi.ts) creates cryptographically secure, time-limited tokens
- **UI adapters** in `ui/src/adapters/openclaw-gateway/` enforce consistent configuration of gateway URLs and authentication headers
- **Server validation** in [`server/src/routes/access.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/access.ts) via `buildJoinDefaultsPayloadForAccept` implements comprehensive security checks with specific error codes
- **Post-join operation** treats OpenClaw agents as native agents with customized heartbeat timeouts and full API access
- The entire flow maintains **security through single-use tokens, protocol enforcement, and hostname allowlisting**

## Frequently Asked Questions

### What protocols does the OpenClaw gateway support?

The OpenClaw gateway strictly requires WebSocket connections. The `buildJoinDefaultsPayloadForAccept` validator in [`server/src/routes/access.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/access.ts) explicitly rejects `http://` or `https://` URLs, returning `openclaw_gateway_url_protocol` for non-WebSocket schemes. Production deployments should use `wss://` for encrypted transport.

### How long does the invite token remain valid?

The token generated by the `createOpenClawInvitePromptSchema` endpoint is short-lived by design—typically minutes, not hours. The exact duration is configurable server-side, but the token is immediately consumed upon successful join and cannot be reused. Failed validation attempts return `openclaw_gateway_auth_header_too_short` or related errors without exposing token state.

### Can multiple OpenClaw instances use the same invite?

No. Each invite prompt generates a unique, single-use token. Attempting to reuse a token after successful join results in `openclaw_gateway_auth_header_missing` or authentication failure. Administrators must generate new invites for each distinct OpenClaw runtime instance they wish to connect.

### Where is the gateway URL stored after agent creation?

The validated gateway URL from `agentDefaultsPayload.url` persists in the agent's join record, retrievable through Paperclip's agent management APIs. This URL serves as the routing target for server-initiated heartbeat messages and asynchronous commands, as implemented in [`server/src/services/built-in-agents.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/services/built-in-agents.ts).