11ff24cd22
- Fix openclaw → openclaw_gateway type key in adapters overview and managing-agents guide - Add missing adapters to overview table: hermes_local, cursor, pi_local - Mark gemini_local as experimental (adapter package exists but not in stable type enum) - Update "Choosing an Adapter" recommendations to match stable adapter set Co-Authored-By: Paperclip <noreply@paperclip.ing> Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
64 lines
2.6 KiB
Markdown
64 lines
2.6 KiB
Markdown
---
|
|
title: Adapters Overview
|
|
summary: What adapters are and how they connect agents to Paperclip
|
|
---
|
|
|
|
Adapters are the bridge between Paperclip's orchestration layer and agent runtimes. Each adapter knows how to invoke a specific type of AI agent and capture its results.
|
|
|
|
## How Adapters Work
|
|
|
|
When a heartbeat fires, Paperclip:
|
|
|
|
1. Looks up the agent's `adapterType` and `adapterConfig`
|
|
2. Calls the adapter's `execute()` function with the execution context
|
|
3. The adapter spawns or calls the agent runtime
|
|
4. The adapter captures stdout, parses usage/cost data, and returns a structured result
|
|
|
|
## Built-in Adapters
|
|
|
|
| Adapter | Type Key | Description |
|
|
|---------|----------|-------------|
|
|
| [Claude Local](/adapters/claude-local) | `claude_local` | Runs Claude Code CLI locally |
|
|
| [Codex Local](/adapters/codex-local) | `codex_local` | Runs OpenAI Codex CLI locally |
|
|
| [Gemini Local](/adapters/gemini-local) | `gemini_local` | Runs Gemini CLI locally (experimental — adapter package exists, not yet in stable type enum) |
|
|
| OpenCode Local | `opencode_local` | Runs OpenCode CLI locally (multi-provider `provider/model`) |
|
|
| Hermes Local | `hermes_local` | Runs Hermes CLI locally |
|
|
| Cursor | `cursor` | Runs Cursor in background mode |
|
|
| Pi Local | `pi_local` | Runs an embedded Pi agent locally |
|
|
| OpenClaw Gateway | `openclaw_gateway` | Connects to an OpenClaw gateway endpoint |
|
|
| [Process](/adapters/process) | `process` | Executes arbitrary shell commands |
|
|
| [HTTP](/adapters/http) | `http` | Sends webhooks to external agents |
|
|
|
|
## Adapter Architecture
|
|
|
|
Each adapter is a package with three modules:
|
|
|
|
```
|
|
packages/adapters/<name>/
|
|
src/
|
|
index.ts # Shared metadata (type, label, models)
|
|
server/
|
|
execute.ts # Core execution logic
|
|
parse.ts # Output parsing
|
|
test.ts # Environment diagnostics
|
|
ui/
|
|
parse-stdout.ts # Stdout -> transcript entries for run viewer
|
|
build-config.ts # Form values -> adapterConfig JSON
|
|
cli/
|
|
format-event.ts # Terminal output for `paperclipai run --watch`
|
|
```
|
|
|
|
Three registries consume these modules:
|
|
|
|
| Registry | What it does |
|
|
|----------|-------------|
|
|
| **Server** | Executes agents, captures results |
|
|
| **UI** | Renders run transcripts, provides config forms |
|
|
| **CLI** | Formats terminal output for live watching |
|
|
|
|
## Choosing an Adapter
|
|
|
|
- **Need a coding agent?** Use `claude_local`, `codex_local`, `opencode_local`, or `hermes_local`
|
|
- **Need to run a script or command?** Use `process`
|
|
- **Need to call an external service?** Use `http`
|
|
- **Need something custom?** [Create your own adapter](/adapters/creating-an-adapter)
|