# Paperclip

Paperclip is an open-source control plane that runs AI agents for a company. An agent that uses the OpenCode runtime can use the exchange as its model provider. Paperclip has no Liquid Inference connector in its catalog. Use the OpenCode adapter's provider setting instead.

This guide follows the Paperclip documentation for the `opencode_local` adapter. Check each step against your Paperclip release.

## Before you start

- A workspace with a balance and a `spend` key. See [API keys](https://inference.ai.exchange/docs/keys.md).
- A Paperclip agent that uses the OpenCode adapter (`opencode_local`).
- A run on the same machine as Paperclip. Paperclip applies the provider setting only to local runs.

## 1. Store the buyer key

Store the key as a Paperclip secret. Do not put the key in the provider setting. Each agent can use its own key and its own spend limit.

## 2. Set the adapter environment

In the agent's OpenCode configuration, add these values to `env`. Refer to the secret for `LIQUID_API_KEY`.

| Variable                         | Value                                                           |
| -------------------------------- | --------------------------------------------------------------- |
| `LIQUID_API_KEY`                 | A reference to the secret from step 1.                          |
| `PAPERCLIP_OPENCODE_PROVIDERS`   | The provider definition below, as one line of JSON.             |
| `PAPERCLIP_OPENCODE_SMALL_MODEL` | `liquid/liquid.auto`. OpenCode uses it for its helper requests. |
| `OPENCODE_ALLOW_ALL_MODELS`      | `true`. This skips the check of OpenCode's own model list.      |

Use this value for `PAPERCLIP_OPENCODE_PROVIDERS`:

```json
{
  "liquid": {
    "npm": "@ai-sdk/openai-compatible",
    "name": "Liquid Inference",
    "options": {
      "baseURL": "https://router.inference.ai.exchange/v1",
      "apiKey": "{env:LIQUID_API_KEY}",
      "headers": { "X-Title": "Paperclip" }
    },
    "models": { "liquid.auto": {} }
  }
}
```

The `X-Title` header identifies Paperclip on the receipt. Paperclip expands `{env:LIQUID_API_KEY}` when it starts the run.

## 3. Choose the model

Set the agent's `model` to `liquid/liquid.auto`. The format is `provider/model`.

OpenCode accepts only a model that the `models` map lists. Add one entry for each model that the agent can use, for example `"liquid.auto:cheapest": {}`. See [Market data](https://inference.ai.exchange/docs/market.md) for the model names.

## 4. Check the first run

Run the agent with a short task. Open **Credits → Receipts** and check for the charge and the `Paperclip` client label.

## Control the cost

Add `x-liquid-cap-usd` to `options.headers` to limit what one request may cost. Paperclip's own budget does not read the exchange's charge. Set a spend limit on the key to limit the total. See [API keys](https://inference.ai.exchange/docs/keys.md) and [Purchasing rules](https://inference.ai.exchange/docs/rules.md).

## Limits of this setup

- Paperclip applies `PAPERCLIP_OPENCODE_PROVIDERS` only when the agent's `dangerouslySkipPermissions` setting is on. This is the default.
- The provider does not appear in Paperclip's **Connectors** page. Paperclip shows no connection and no credit information for it.

## Troubleshooting

| Symptom                                    | Cause and fix                                                                                          |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| `Configured OpenCode model is unavailable` | Add the model to `models`, or set `OPENCODE_ALLOW_ALL_MODELS` to `true`.                               |
| The run stops before the first answer      | Set `PAPERCLIP_OPENCODE_SMALL_MODEL` to a model that the exchange serves.                              |
| The provider setting has no effect         | Check that the run is local and that `dangerouslySkipPermissions` is on. Check that the JSON is valid. |
| `401`                                      | Check that the secret holds a valid key.                                                               |
| `402`                                      | Add credit to the workspace or check the key's spend limit.                                            |
| `output_bound_unsupported`                 | Select a model with a live offer that accepts the requested output limit.                              |

See [Errors](https://inference.ai.exchange/docs/errors.md) for the exchange's error codes.

## Next steps

- [OpenCode](https://inference.ai.exchange/docs/connect-opencode.md): the same runtime, set up without Paperclip.
- [API keys](https://inference.ai.exchange/docs/keys.md): key scope and spend limits.
- [Purchasing rules](https://inference.ai.exchange/docs/rules.md): request caps and presets.