@ivydigital/paperclip-adapter-openrouter

External Paperclip adapter for OpenRouter. Run any Paperclip agent on any free or paid OpenRouter model — DeepSeek, Claude, GPT, Gemini, Llama, Hermes, Qwen, Kimi — without spawning an external CLI. The adapter speaks OpenRouter's HTTP API directly.

Install (from inside Paperclip)

In a Paperclip deployment, install this package as an external adapter plugin so the server registers it on next startup:

npm install --prefix $PAPERCLIP_DATA_DIR/adapter-plugins @ivydigital/paperclip-adapter-openrouter

Then restart the server (or POST to the adapter-plugin reload endpoint). The new adapter type openrouter will appear in the Agent config picker.

Contract

This package is a Paperclip external adapter. It exports a top-level createServerAdapter() factory, which Paperclip's plugin loader calls to get a ServerAdapterModule:

import { createServerAdapter } from "@ivydigital/paperclip-adapter-openrouter";

const adapter = createServerAdapter();
// adapter.type === "openrouter"
// adapter.execute, .testEnvironment, .listModels, .sessionCodec, .models, .agentConfigurationDoc

Agent configuration

| Field | Type | Default | Description | |-------|------|---------|-------------| | apiKey | string (secret) | — | Required. OpenRouter API key. | | model | string | deepseek/deepseek-chat-v3-0324:free | Any OpenRouter model id. | | baseUrl | string | https://openrouter.ai/api/v1 | Override for staging or self-hosted gateways. | | temperature | number | 0.2 | Sampling temperature. | | maxTokens | number | (provider default) | Hard cap on output tokens. | | systemPrompt | string | (built-in) | Replace the default system prompt. | | timeoutMs | number | 300000 | Per-request timeout in ms. | | extraHeaders | object | {} | Extra HTTP headers (e.g. ranking headers). | | provider | object | — | Forwarded to OpenRouter as the provider block (routing/fallback). |

apiKey falls back to the OPENROUTER_API_KEY environment variable when not set explicitly — useful for containerized deployments.

Free vs paid models

OpenRouter exposes both free and paid models behind the same API. Free models include the :free suffix in their id (e.g. deepseek/deepseek-r1:free). Free tiers have stricter rate limits. listModels() returns the full live catalog, sorted by label.

Development

npm install
npm run typecheck
npm run build
npm test

Publishing

This adapter is published to npm. Bump the version in package.json, then:

npm run build
npm publish --access public

CI uses an NPM_TOKEN from the org secret store; do not run npm publish with a personal token.

License

MIT