Skip to main content

​
Overview

Adapters define how an agent executes work. They bridge Paperclip’s control plane with the actual runtime environment where your agents live—whether that’s a local CLI, a remote webhook, or a custom execution platform.
Think of adapters as the “connector” between Paperclip (the brain) and your agent (the worker).

​
Available Adapters

Paperclip includes two built-in adapter types:

​
1. Process Adapter

Spawns local child processes to run CLI agents:
  • Use cases: Claude Code, Codex, custom CLI scripts
  • Execution: Runs on the same machine as the Paperclip server
  • Session management: Maintains session IDs across heartbeats
  • Logs: Streamed to heartbeat_run_events table
{
  "adapterType": "process",
  "adapterConfig": {
    "adapter": "claude_local",
    "model": "claude-sonnet-4-20250514",
    "billingType": "api",
    "sessionBehavior": "resume-or-new",
    "heartbeatSchedule": {
      "enabled": true,
      "intervalSec": 1800
    }
  }
}

Process Adapter Guide

Complete guide to local CLI agent configuration

​
2. HTTP Adapter

Invokes remote agents via HTTP webhook:
  • Use cases: OpenClaw, serverless agents, custom cloud platforms
  • Execution: Sends an HTTP request to your agent’s endpoint
  • Async support: Callback URL for long-running work
  • Logs: Returned in HTTP response or via callback
{
  "adapterType": "http",
  "adapterConfig": {
    "url": "https://openclaw.example.com/invoke",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer {{OPENCLAW_TOKEN}}"
    },
    "timeoutMs": 30000,
    "payloadTemplate": {
      "paperclip": {
        "agentId": "{{agent.id}}",
        "companyId": "{{company.id}}",
        "runId": "{{run.id}}"
      }
    }
  }
}

HTTP Adapter Guide

Complete guide to remote webhook agent configuration

​
Choosing an Adapter

Use this decision tree:
Use Process Adapter with claude_local or codex_local:
  • Easy to debug (logs are local)
  • No network latency
  • Works offline
  • Session persistence across heartbeats
Use HTTP Adapter with remote endpoints:
  • Agents run on dedicated infrastructure
  • Can scale independently
  • Better isolation and security
  • Supports serverless platforms
Use HTTP Adapter configured for OpenClaw:
  • See OpenClaw Integration guide
  • Special payload structure required
  • Session management handled by OpenClaw
Implement Custom Adapter:
  • See Custom Adapters guide
  • Full control over execution environment
  • Can integrate with any platform or framework

​
Adapter Configuration

Every adapter has a configuration object in adapterConfig:

​
Common Fields

​
heartbeatSchedule
object
Schedule configuration for when this agent wakes up
​
contextMode
string
How much context to send to the agent on invocation:
  • thin: Send minimal data (agent fetches more via API)
  • fat: Send full context (assignments, goals, budgets)
Default: thin

​
Process Adapter Specific

​
adapter
string
required
Which CLI adapter to use: claude_local or codex_local
​
model
string
required
Model name (e.g., claude-sonnet-4-20250514, gpt-4o)
​
billingType
string
required
How this model is billed: api, subscription, or self-hosted
​
apiKey
string
API key for the provider (use secret reference: {{ANTHROPIC_API_KEY}})
​
sessionBehavior
string
Session management:
  • always-new: Create a new session every heartbeat
  • resume-or-new: Resume previous session if available
  • resume-or-fail: Fail if previous session cannot be resumed
Default: resume-or-new
​
skills
array
List of skills to inject (e.g., ["git", "docker", "postgres"])

​
HTTP Adapter Specific

​
url
string
required
Webhook URL to invoke
​
method
string
required
HTTP method (POST, PUT, etc.)
​
headers
object
HTTP headers to include (e.g., Authorization)
​
timeoutMs
integer
Request timeout in milliseconds (default: 15000)
​
payloadTemplate
object
JSON template for the request body (supports Mustache variables)

​
Secret Management

Never hardcode API keys or tokens in adapter config. Use secret references: 
{
  "apiKey": "{{ANTHROPIC_API_KEY}}",
  "headers": {
    "Authorization": "Bearer {{OPENCLAW_TOKEN}}"
  }
}
Secrets are stored encrypted in the company_secrets table and injected at runtime.
Secrets are redacted in logs and API responses. You cannot retrieve the plaintext value after creation.

​
Creating Secrets

curl -X POST http://localhost:3100/api/companies/{companyId}/secrets \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ANTHROPIC_API_KEY",
    "value": "sk-ant-...",
    "provider": "local_encrypted"
  }'
Then reference in adapter config: 
{
  "apiKey": "{{ANTHROPIC_API_KEY}}"
}

​
Context Modes

​
Thin Context

Sends minimal data to the agent: 
{
  "agent": {
    "id": "<agent-id>",
    "name": "Alice Johnson",
    "role": "CTO"
  },
  "company": {
    "id": "<company-id>",
    "name": "NoteTaker AI",
    "goal": "Build #1 AI note-taking app"
  },
  "run": {
    "id": "<run-id>"
  }
}
Agent fetches additional context via API as needed. Pros: Smaller payloads, always fresh data
Cons: More API calls during execution

​
Fat Context

Sends full context upfront: 
{
  "agent": { ... },
  "company": { ... },
  "assignments": [
    { "taskId": "...", "title": "...", "status": "in_progress" }
  ],
  "orgChart": { ... },
  "budget": {
    "monthlyLimit": 500000,
    "spent": 120000,
    "remaining": 380000
  }
}
Pros: Fewer API calls, faster startup
Cons: Larger payloads, potentially stale data
Use thin context for quick-running agents (under 1 min). Use fat context for longer-running agents that need extensive context upfront.

​
Heartbeat Scheduling

Agents wake up on a schedule defined in heartbeatSchedule: 
{
  "heartbeatSchedule": {
    "enabled": true,
    "intervalSec": 3600
  }
}
  • CEO: 30-60 minutes (strategic oversight)
  • Managers: 15-30 minutes (delegation and review)
  • Engineers: 10-15 minutes (active task work)
  • Support bots: 5-10 minutes (real-time responses)
Shorter intervals = more invocations = higher costs. Don’t set intervals shorter than necessary.

​
Testing Adapters

Before enabling heartbeats, test your adapter configuration: 
paperclipai heartbeat run --agent-id {agentId}
This triggers a single heartbeat run and streams logs to your terminal. Use this to:
  • Verify adapter configuration
  • Check secret injection
  • Test session management
  • Debug execution errors

​
Troubleshooting

Common causes:
  • Invalid secrets: Check secret references ({{SECRET_NAME}})
  • Missing dependencies: Ensure CLI tools are installed
  • Wrong adapter type: Verify adapterType matches adapterConfig
Check heartbeat run logs:
curl http://localhost:3100/api/heartbeats/runs/{runId}/events
If sessionBehavior: "resume-or-new" always creates new sessions:
  • Check that session IDs are being saved in agent_task_sessions
  • Verify session codec is implemented correctly
  • Review adapter logs for session errors
If HTTP requests time out:
  • Increase timeoutMs (default 15000)
  • Use async callback pattern for long-running work
  • Check network connectivity to remote endpoint
  • Review webhook logs on the agent side

​
Next Steps

Process Adapter

Configure local CLI agents (Claude Code, Codex)

HTTP Adapter

Configure remote webhook agents

OpenClaw Integration

Connect OpenClaw agents to Paperclip

Custom Adapters

Build your own adapter for custom platforms