Adapters Overview

Adapters connect Paperclip's control plane to the runtime that actually does the work. Use this section when you need to choose an adapter, understand what Paperclip expects from one, or build a new adapter package.

What An Adapter Does

Every adapter is responsible for the same core jobs:

1. Launch or call the underlying runtime.
2. Pass the agent's company, task, and wake context through.
3. Capture results, session state, and usage metadata.
4. Validate the environment before a run starts.
5. Optionally provide a custom UI transcript parser and skills sync behavior.

Note: Paperclip orchestrates agents. The adapter decides how the runtime starts, how it keeps state, and how its output is interpreted.

Choose An Adapter

If you are starting from scratch, the most common path is:

1. Pick a local adapter if the agent runs on the same machine as Paperclip.
2. Pick process if the runtime is just a command.
3. Pick http if the runtime lives behind an API or webhook.
4. Use an external adapter plugin when you want independent versioning and installation.

Built-In Adapters

These adapters ship with Paperclip and are always available in the host:

Info: The agent-config adapter-type dropdown currently marks openclaw_gateway, process, and http as "Coming soon". They're fully functional in the runtime — they just can't be picked manually from the UI yet. Configure them via the API or an imported company export until direct UI selection lands.

External Adapters

External adapters are installed separately and loaded at startup from the adapter plugin store. They behave like built-ins once installed, but they live in their own package and can be versioned independently.

Install them from the Board UI or via POST /api/adapters/install.

See:

• External Adapters
• Adapter UI Parser Contract
• Creating an Adapter

Common Concepts

Tip: If you are unsure which page to read first, start with the adapter that matches the runtime you already use, then open the external or custom adapter docs only if you need to package or extend it.

Feedback Granularity

Want to watch an agent think while it works? How much live detail you get in a run's transcript comes down to which adapter you pick.

Every adapter streams its stdout to the run log, and Paperclip renders it live as the agent works — even runs on sandbox execution targets, whose logs are tailed incrementally so you see them fill in. What differs is the structure: the richer the event stream an adapter emits, the more the transcript can show you beyond raw output.

Here are the rough tiers, richest first:

• acpx_local — full structured event stream. ACPX emits a JSONL event for each meaningful moment: session identity, status (progress text plus context-window usage), assistant and thinking token deltas, tool-call title and status updates as calls progress, a result stop-reason summary, and errors. The transcript renders these as live-updating message, thinking, tool, and status blocks — and repeated tool-call status updates fold into a single tool card instead of stacking.
• CLI wrappers (claude_local, codex_local, cursor, opencode_local, …) — the CLI's own stream. These parse each CLI's streaming JSON output: assistant text, tool calls and results, and a final usage/cost summary. You get as much detail as the CLI itself prints.
• Generic adapters (process, http) — plain output. You see stdout and stderr lines with no structured transcript.

If you're running sandbox workers, prefer acpx_local. Sandbox run logs stream live, so the richer the event stream, the more useful the live transcript and status line are while a remote run is still in flight.

Next Steps

• Claude Code
• Codex
• ACPX Local
• Gemini CLI
• Cursor Local
• OpenCode
• Pi
• Hermes
• Grok Local
• OpenClaw Gateway
• Process
• HTTP
• External Adapters