Paperclip OpenRouter Adapter

External Paperclip adapter for running agents through OpenRouter chat completions.

This package registers adapter type openrouter via Paperclip's external adapter system. It calls OpenRouter directly, so it only needs an OpenRouter API key and does not depend on a local coding CLI.

Install

From the Paperclip UI:

Settings -> Adapters -> Install from npm -> @gorkamolero/paperclip-adapter-openrouter

Or through the local API:

curl -X POST http://localhost:3100/api/adapters/install \
  -H 'Content-Type: application/json' \
  -d '{"packageName":"@gorkamolero/paperclip-adapter-openrouter"}'

For local development:

npm run build
curl -X POST http://localhost:3100/api/adapters/install \
  -H 'Content-Type: application/json' \
  -d '{"packageName":"/absolute/path/to/paperclip-adapter-openrouter","isLocalPath":true}'

Restart Paperclip after installing or updating a local adapter so startup loading and the UI parser are both refreshed.

Configuration

Set OPENROUTER_API_KEY in ~/.paperclip/.env, in the Paperclip server environment, or provide apiKey in the agent adapter config.

Common adapter config:

{
  "cwd": "/absolute/path/to/git/repo",
  "model": "openrouter/fusion",
  "maxTurns": 25,
  "maxTokens": 4096,
  "paperclipApiUrl": "http://localhost:3100"
}

Any of OpenRouter's 300+ models works — set model to any OpenRouter id. Defaults to openrouter/auto. The list below is just UI dropdown shortcuts; manual ids work too via the config combobox:

• openrouter/fusion
• openrouter/auto
• deepseek/deepseek-chat-v3-0324:free
• meta-llama/llama-3.3-70b-instruct:free
• google/gemini-2.0-flash-exp:free

Manual OpenRouter model ids also work through the combobox config field.

Behavior

On each heartbeat, the adapter:

1. Reads the current Paperclip wake context and current issue.
2. Marks the issue in_progress when an issue id is available.
3. Runs an OpenRouter /chat/completions tool loop with Paperclip board tools.
4. Posts the final assistant response as a comment.
5. Marks successful issue runs done.
6. Returns usage, provider, model, and cost metadata when OpenRouter reports them.

Verified Working

Verified locally on 2026-06-27:

• Adapter inventory: type:"openrouter", source:"external", loaded:true, version:"0.1.0".
• Throwaway company: b2e92cd6-e999-4c39-adf3-d0481d2b2d4b.
• Agent: 1e1f9f84-8463-4fdd-9648-26a917e79164, adapterType:"openrouter", model openrouter/fusion.
• Issue: OPE-1 / a423004f-2f09-452f-b32c-97acaa334a54.
• Successful heartbeat run: 0f3d0a56-eef1-4ff1-9540-ca44c2bb2fd5, adapterType:"openrouter", status succeeded.
• Exact proof comment: ADAPTER_EXEC_OK.
• Final issue status: done.
• Reported OpenRouter usage: 19,371 input tokens, 237 output tokens, cost $0.10278.

Prior Art

This implementation credits the community OpenRouter adapter by talhamahmood666/paperclip-adapter-openrouter as prior art. This package was rebuilt around Paperclip's current external adapter contract: createServerAdapter(), ServerAdapterModule, and dynamic UI parser loading.

Development

npm install
npm run build
npm run smoke
npm pack --dry-run

License

MIT © Gorka Molero (gorkamolero)