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

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 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:

{
  "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
• Configuration UI: 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, 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:

{
  "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 (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 (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:

# 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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}