OpenClaw + Paperclip Integration: How to Connect, Configure, and Test It (2026)
One OpenClaw agent is a tool. Ten OpenClaw agents with no governance is a $4,000 weekend API bill and a Slack channel full of half-finished work.
That is the gap Paperclip fills. OpenClaw handles the runtime — prompts, tools, memory, MCP. Paperclip handles the part OpenClaw does not: org structure, monthly budgets, heartbeat schedules, approval gates, and a single dashboard where a human can pause any agent at any time.
This guide walks through the integration end to end. You will paste four config fields into Paperclip, run one test command, and read one log output. If anything breaks, the error codes are predictable and fixable. At the end, if you would rather not run a gateway on a VPS yourself, there is a managed path that skips the infrastructure steps entirely.
Everything below reflects the current Paperclip + OpenClaw behavior as of April 2026 — the adapter shape, the CLI commands, the session lifecycle. No speculation, no old syntax.
Why one OpenClaw agent is not enough once the work gets serious
OpenClaw on its own is excellent at one job: take a prompt, route it through tools, produce a result. If you are using it as a coding assistant, a research agent, or a chat surface on WhatsApp, you are done. Nothing else needed.
The trouble starts the moment you have more than one agent and more than one goal.
You want an engineering agent and a research agent. The research agent should only run in the morning. The engineering agent should be able to deploy, but only after a human approves. Neither should burn more than $200 of tokens per month. If one crashes, the other should keep going.
You can cobble that together with cron, environment variables, and a shared database. People have. It ends badly. The places it breaks are always the same:
- Two agents write to the same memory file and clobber each other
- One agent runs a tool loop overnight and drains the account
- A junior dev merges a PR an agent wrote, and nobody can trace why the agent wrote it
- Scheduled runs stop and nobody notices for three days
These are not OpenClaw problems. They are coordination problems. OpenClaw is — by design — a single-agent runtime. It does not know about your other agents, your calendar, or your billing.
That is exactly the surface Paperclip claims.
What Paperclip actually is
Paperclip is an open-source, self-hosted orchestration layer. The project positions itself as "the human control plane for AI labor." The repo is paperclipai/paperclip on GitHub, MIT-licensed, Node.js 20+ with an embedded Postgres.
Strip the positioning and here is what it does concretely:
Heartbeats, not chat. Agents wake on a schedule (default: hourly), check their queue, do some work, and sleep. They are not listening to a chat channel. This makes cost and scheduling predictable.
Budgets per agent. Every agent gets a monthly dollar cap. When the cap is hit, the agent stops accepting heartbeats until next month or a human tops it up. Runaway loops hit a wall.
Approval gates. Any action tagged as sensitive — deploys, customer emails, refunds — parks itself in a human queue. Nothing happens until someone clicks approve.
Org charts. Agents report to other agents. A "CTO" agent can delegate to an "engineer" agent and review its output. Delegation is not magical — it is literally a second heartbeat call to the subordinate.
Governance dashboard. One screen to see all runs, all costs, all queued approvals, and a kill switch on every agent.
One line from a user on the Paperclip homepage captures the split cleanly: "OpenClaw is an employee. Paperclip is the company." That is also the right mental model for the integration — OpenClaw stays as-is, Paperclip wraps around it.
Install is a single command once you have Node 20 and pnpm:
npx paperclipai onboard --yes
The API comes up at http://localhost:3100. Data lives in an embedded Postgres under your home directory. No account, no cloud, nothing phoned home by default.
How the OpenClaw–Paperclip handshake actually works
The integration uses a webhook. That is the whole thing. Paperclip, on every heartbeat, makes one HTTP POST to the OpenClaw gateway, waits for a response, and logs it.
Here is the round trip in order:
- Paperclip scheduler fires. The scheduler decides it is time for
agent_cto_01to run. - Paperclip builds a payload. It includes the prompt for this heartbeat, any context the agent needs, and a
paperclipblock with run and task IDs. - Paperclip POSTs to the OpenClaw gateway. Uses the webhook URL and bearer token you configured.
- OpenClaw runs. The gateway spins up (or resumes) a session, executes the prompt against whatever tools and MCP servers the agent has, and produces a result.
- OpenClaw responds. Either synchronously with a 2xx and the full result, or asynchronously with a 202 and a callback URL it will hit later.
- Paperclip stores the
sessionId. On the next heartbeat for the same agent, it sends that ID back so OpenClaw can restore memory, workspace, and file state. - Paperclip logs the run. Cost, duration, output, any errors, all written to the run log you can pull with the CLI or the dashboard.
The session handoff is the subtle bit worth understanding. OpenClaw returns a sessionId in every response. Paperclip hangs onto that ID and passes it back next cycle. That is what makes an agent feel continuous across heartbeats instead of cold-starting every hour. Lose the session ID and the agent effectively forgets everything each run.
Network-wise, the webhook can point anywhere the Paperclip process can reach. That means:
- Same machine —
http://127.0.0.1:18789 - Private mesh — a Tailscale or WireGuard address
- Public HTTPS — a reverse-proxied URL with TLS (required if you care about the bearer token not leaking)
If you are running everything on one laptop for a demo, 127.0.0.1 is fine. If you are running Paperclip on a separate box from OpenClaw, you need one of the last two. Do not put the OpenClaw gateway on the public internet with only a bearer token — put TLS in front of it or hide it behind a private network.
The four adapter fields you actually need to fill in
Paperclip stores its adapters as JSON. For OpenClaw, the config is four fields. Here is the minimum working version:
{
"adapter": "openclaw",
"webhookUrl": "http://127.0.0.1:18789",
"webhookAuthHeader": "Bearer ${secrets.openclaw_gateway_token}",
"payloadTemplate": {},
"timeoutSec": 30
}
Walking each field:
adapter — always the string openclaw. This tells Paperclip which built-in integration to use. Do not invent a new name.
webhookUrl — the HTTP(S) endpoint of your OpenClaw gateway. Local default is http://127.0.0.1:18789. On Clawctl it is https://<your-tenant>.tenant.clawctl.com (more on that shortly). Trailing slash does not matter.
webhookAuthHeader — the full value of the Authorization header Paperclip will send. Always Bearer <token>. Put the token in Paperclip's secrets manager and reference it with ${secrets.openclaw_gateway_token} — do not paste raw tokens into the config, you will commit them to git at some point.
payloadTemplate — overrides for the default request shape. Leave as {} unless you know you need to rewrite keys. Paperclip's default template is already what OpenClaw expects.
timeoutSec — how long Paperclip waits for a sync response before giving up. 30 seconds is the default and fine for most chat-shaped work. Long-running coding or research tasks should go async (more on that below).
What the request payload looks like
With the default template, the body Paperclip sends to the gateway looks like this:
{
"prompt": "Review the open PRs on the backend repo and leave one sentence of feedback each.",
"context": {
"org": "acme",
"agent": "engineer_01",
"previousSessionId": "sess_b91c..."
},
"paperclip": {
"runId": "hb_run_abc123",
"agentId": "agent_cto_01",
"taskId": "task_review_prs_weekly"
}
}
The paperclip block is what OpenClaw's adapter mode uses to echo IDs back into logs. The context.previousSessionId is what makes continuity work. prompt is the actual job.
Sync vs async responses
OpenClaw can answer in two modes. Paperclip handles both automatically — your config does not change, but knowing which you are getting matters for debugging.
Sync (2xx response): OpenClaw finishes the work inside your timeoutSec window and returns the full result in the HTTP response. Best for prompts that take seconds, not minutes.
Async (202 Accepted): OpenClaw returns 202 immediately with a callback URL. It does the work in the background and POSTs the result back to Paperclip when done. Best for coding, research, or anything that might take 2+ minutes.
The rough rule: under 30 seconds, sync. 30 seconds to 5 minutes, bump timeoutSec and keep sync. Over 5 minutes, use async. If your heartbeats are timing out and the agent is still actually working, that is the signal to move to async, not to keep cranking up the timeout.
Testing the integration (the three commands that tell you everything)
Configuration in, now prove it works. The whole test takes about two minutes.
Step 1 — pair the gateway if you have not
The OpenClaw gateway rejects unknown clients by default. First call from a new Paperclip install triggers a pairing prompt on whichever host runs the gateway.
openclaw devices approve --latest
If you run this on managed hosting, there is a dashboard button instead. Either way, pair once and the token stays valid until you rotate it.
Step 2 — trigger a heartbeat manually
Do not wait for the cron to fire. Force one:
paperclip heartbeat run --agent-id agent_cto_01
A healthy run prints a run ID and returns in a couple of seconds. A broken run exits with an error — almost always one of the four codes in the next section.
Step 3 — read the log
Grab the runId from step 2 and pull the log:
paperclip heartbeat logs --run-id hb_run_7f3a
The output shows: the request Paperclip sent, the HTTP status from OpenClaw, the response body (including sessionId), any tool calls the agent made, total tokens used, total cost in dollars, and the duration.
If you see a 2xx status, a non-empty sessionId, and zero error codes, the integration is working. Schedule the agent for real heartbeats and move on.
The four error codes that cover 95% of failures
When integrations break, the gateway reports one of four codes. They map to exactly four fixes.
openclaw_gateway_unreachable — Paperclip cannot open a TCP connection to the URL. Cause: wrong URL, firewall, gateway process not running, VPN disconnected. Fix: curl -v <webhookUrl>/health from the Paperclip host. If curl fails, networking is the problem, not the adapter.
openclaw_auth_failed — Paperclip reached the gateway but the bearer token was rejected. Cause: typo, wrong token, token rotated but not updated in Paperclip secrets. Fix: re-copy the token from wherever it was issued (dashboard, CLI, .env), paste into Paperclip secrets as openclaw_gateway_token, re-run.
openclaw_gateway_timeout — Gateway accepted the request but did not respond within timeoutSec. Cause: the prompt is doing real work and needs more time. Fix: raise timeoutSec to 120 or 300. If jobs still exceed 5 minutes, switch that agent to async mode.
openclaw_gateway_pairing_required — First call from a new client. Fix: run the pairing command in step 1 above. One-time fix per client.
If you see any other error, the body of the response usually has a plain-English reason. Most commonly: OpenClaw has no API key configured for the provider the agent wants to call, or a tool the agent needs is not whitelisted.
The problem with doing all of this yourself
Everything above works. It is also six hours of setup before you run your first real heartbeat:
- Provision a VPS
- Install Node, pnpm, Docker
- Install OpenClaw and the docker-proxy sidecar
- Configure at least one LLM provider
- Configure whatever channels the agent needs (WhatsApp, Telegram, Slack)
- Get a domain, point DNS, issue a TLS cert, front the gateway with Traefik or nginx
- Configure Paperclip
- Pair the gateway
- Actually test it
Every one of those steps has a version mismatch, a permission issue, or a DNS propagation wait that eats a half-hour. The Paperclip integration itself is clean. The OpenClaw host underneath it is the long part. If you are running a team and you want to spend that time on agents instead of on infrastructure, you have two options: pay someone to set it up, or use a managed host.
The managed shortcut: Clawctl
Clawctl is managed OpenClaw hosting. It exists specifically to kill the six hours above.
You sign up, pick a plan, and within a couple of minutes you get:
- A dedicated OpenClaw gateway at
https://<your-tenant>.tenant.clawctl.com, TLS-terminated, HTTP/1.1-safe for WebSocket clients - A bearer token, rotatable from the dashboard
- A per-tenant sandbox with docker-proxy already wired up (no raw
docker.sockexposure) - Provider setup for Anthropic, OpenAI, Gemini, Grok, OpenRouter, Ollama, and opencode-zen via a UI — paste keys, done
- Channel provisioning for WhatsApp, Telegram, Discord, Slack, and Mattermost — same UI
- MCP servers for Stripe, GitHub, and any stdio/HTTP catalog entry, isolated per tenant
- Auto-recovery, health gates, and a redeploy button
For the Paperclip adapter, this collapses the six-hour setup into two copy-pastes:
{
"adapter": "openclaw",
"webhookUrl": "https://acme-7f3a.tenant.clawctl.com",
"webhookAuthHeader": "Bearer ${secrets.openclaw_gateway_token}",
"payloadTemplate": {},
"timeoutSec": 30
}
- Copy your gateway FQDN from the Clawctl dashboard → paste into
webhookUrl. - Copy your gateway token from Settings → Tokens → paste into Paperclip secrets as
openclaw_gateway_token.
That is the whole integration. No VPS, no Tailscale, no TLS cert, no pairing prompt to babysit. Pairing is handled in the dashboard — one click and the device is approved. Heartbeats start flowing.
The part nobody tells you about managed OpenClaw hosting is the upgrade story. OpenClaw ships new versions every couple of weeks. Self-hosted, that is on you — test locally, rebuild images, redeploy, pray nothing broke. On Clawctl, it is a maintenance window. Same with docker-proxy CVEs, Traefik config drift, and DNS certificate renewals. Paperclip does not care which of those you are paying for, because the webhook shape is stable either way — but one path involves you, and the other path does not.
If you want to try it, the free tier is enough to point Paperclip at for testing. When you grow into a real team and real budgets, the pricing is per-tenant and per-seat, not per-agent-call, so you can add Paperclip agents without the host bill scaling with them.
Deploy a managed OpenClaw gateway for Paperclip →
Frequently Asked Questions
What is Paperclip and how does it relate to OpenClaw?
Paperclip is an open-source orchestration layer — a control plane — that sits above OpenClaw. OpenClaw runs a single agent inside a sandbox. Paperclip turns that agent into a member of an organization with roles, budgets, heartbeats, and approval gates. A common phrasing from the Paperclip team: OpenClaw is the employee, Paperclip is the company.
Do I need Paperclip to use OpenClaw?
No. OpenClaw runs fine on its own for single-agent chat and tool use. You need Paperclip once you want multiple agents working toward a shared goal, monthly budgets per agent, scheduled heartbeat execution, or human approval gates before sensitive actions.
What webhook URL does Paperclip expect for the OpenClaw adapter?
Paperclip calls the OpenClaw gateway HTTP endpoint. Locally that is http://127.0.0.1:18789. On a VPS you typically put it behind Tailscale or HTTPS. On Clawctl it is https://<your-tenant>.tenant.clawctl.com — already TLS-terminated and bearer-token protected.
How do I test that Paperclip and OpenClaw are actually talking?
Run paperclip heartbeat run --agent-id <id> to trigger one cycle, then paperclip heartbeat logs --run-id <run> to read the round-trip. A healthy run shows a 2xx response from the gateway, a sessionId in the response body, and no openclaw_gateway_* error codes.
Why does my heartbeat fail with openclaw_gateway_pairing_required?
The OpenClaw gateway uses device pairing for new clients. Run openclaw devices approve --latest on the machine hosting the gateway (or approve from the Clawctl dashboard if you are on managed hosting). The next heartbeat should connect.
Can I run Paperclip against a managed OpenClaw host instead of self-hosting?
Yes. Clawctl is managed OpenClaw hosting. You get a dedicated gateway FQDN, a bearer token, channel integrations, and the docker-proxy sandbox without installing anything. Paste the gateway URL and token into your Paperclip OpenClaw adapter and skip the VPS setup.
Next steps:
- If you have OpenClaw running already: install Paperclip with
npx paperclipai onboard --yes, drop in the four-field adapter config, run one test heartbeat. - If you do not want to run OpenClaw yourself: provision a tenant on Clawctl, copy the gateway URL and token, paste into Paperclip. You are done.
Related reading: