# OpenClaw

OpenClaw is a personal agent that runs on your computer and answers in your
chat apps. These steps install the Liquid Inference plugin. The plugin adds the
exchange to OpenClaw as the model provider `liquid`.

- The plugin holds the exchange URL and the request headers.
- OpenClaw saves the buyer key in its credential store.

## Start with the Liquid CLI

The [Liquid CLI](https://inference.ai.exchange/docs/cli.md) can start OpenClaw with the exchange as its provider. OpenClaw keeps its settings in a file, so set it up one time with the steps below. `liquid connect openclaw` prints the same setup with your model filled in. Then start a session with `liquid openclaw`.

```bash
curl -fsSL https://inference.ai.exchange/cli/install.sh | bash
liquid login
liquid connect openclaw
liquid openclaw
```

## Before you start

- A workspace with a balance and a `spend` key. See [API keys](https://inference.ai.exchange/docs/keys.md).
- OpenClaw 2026.10.5 or later, on Node 24.16 or later. OpenClaw refuses to install on an older Node.

## 1. Install OpenClaw

```bash
npm install -g openclaw
```

If you already use OpenClaw, keep your install. The steps below add a provider
and keep your channels, agents and other providers.

## 2. Export the buyer key

Replace the placeholder with your buyer key. Use the same shell for each
command below.

```bash
export LIQUID_API_KEY=sk-liquid-...
```

| Setting          | Purpose                                      |
| ---------------- | -------------------------------------------- |
| `LIQUID_API_KEY` | The buyer key that step 3 saves in OpenClaw. |

After step 3, OpenClaw does not read this variable. A gateway that runs as a
service uses the saved key.

## 3. Install the plugin and select the model

```bash
openclaw plugins install clawhub:@architect-xyz/openclaw-liquid-inference@0.1.3 --accept-capabilities &&
printf '%s\n' "$LIQUID_API_KEY" | openclaw models auth paste-api-key --provider liquid --agent main &&
openclaw config set agents.defaults.model.primary "liquid/liquid.auto"
```

The commands do these things:

1. The first command installs the
   [Liquid Inference plugin](https://github.com/architect-xyz/openclaw-liquid-inference)
   from ClawHub. It adds the provider `liquid` and keeps your other providers.
   `--accept-capabilities` accepts what the plugin declares: a model provider.
2. The second command saves the key in OpenClaw's credential store, under the
   profile `liquid:manual` of the agent `main`. Other agents use the key of
   `main`. The key is not in `openclaw.json`.
3. The third command makes the model the default for new sessions.

The `&&` at the end of a line stops the list when a command fails.

To change the key, run the second command again with the new key. If
`agents.defaults.authInheritance` names an agent other than `main`, put that
agent's id after `--agent`.

The plugin sets these values for the provider:

| Setting         | Value                                                      | Purpose                                |
| --------------- | ---------------------------------------------------------- | -------------------------------------- |
| Exchange URL    | `https://router.inference.ai.exchange/v1`                  | Where OpenClaw sends model requests.   |
| `api`           | `openai-completions`                                       | Sends Chat Completions requests.       |
| `contextWindow` | From the exchange's model list; `128000` for `liquid.auto` | When OpenClaw compacts a long session. |
| `maxTokens`     | `16384`                                                    | The output limit of each request.      |

The plugin reads the exchange's model list at start, so `openclaw models list --refresh` shows every model on the exchange.

OpenClaw sends these headers with each model request:

| Header             | Value      | Purpose                             |
| ------------------ | ---------- | ----------------------------------- |
| `X-Title`          | `OpenClaw` | Identifies OpenClaw on the receipt. |
| `x-liquid-cap-usd` | `1`        | Limits the charge for each request. |

To send another header, such as a purchasing rule, set
`plugins.entries.liquid.config.headers`. See [Purchasing rules](https://inference.ai.exchange/docs/rules.md).

## 4. Send a first request

```bash
openclaw agent exec --json "Reply with the word ready"
```

The command runs one turn on the local agent and prints JSON. Check two things:

- `final` contains `ready`.
- **Credits → Receipts** shows the charge and the OpenClaw client label.

## 5. Start a session

```bash
openclaw chat
```

`openclaw chat` opens the terminal UI on the local agent. A gateway that is
already running uses the new provider without a restart.

To use another model, run the last command of step 3 again with that model.
Any name on the exchange works as `liquid/<name>`: an exact model, a router
model or a preset. See [Connect an app](https://inference.ai.exchange/docs/connect-overview.md).

## Control the cost

The `x-liquid-cap-usd` header limits each request. To set a different cap:

```bash
openclaw config set plugins.entries.liquid.config.capUsd 0.25 --strict-json
```

The request cap does not limit the total charge. A task can cause several requests, and an agent that answers your chat apps can run many tasks each day. Set a spend limit on the key to limit total spend. See [API keys](https://inference.ai.exchange/docs/keys.md).

Use a preset for other purchasing rules. See [Purchasing rules](https://inference.ai.exchange/docs/rules.md).

## Refusals and fallback models

OpenClaw sends a refused request again before it shows an error:

| Response | What OpenClaw does                        |
| -------- | ----------------------------------------- |
| `429`    | Tries up to 10 times in about 3 minutes.  |
| `503`    | Tries up to 8 times in about 90 seconds.  |
| `400`    | Shows the error at once.                  |
| `402`    | Marks the key as disabled for 10 minutes. |

A refused request costs nothing. The exchange sends `402` when the balance or a
spend limit does not cover the request. OpenClaw tries the saved key again on
the next turn, so a turn after you add funds or raise the limit works.

### Fallback models

If `agents.defaults.model.fallbacks` names a model at another provider, OpenClaw sends each refused request to that provider. The turn succeeds, but:

- The other provider charges you.
- No Liquid Inference receipt shows the request.

To keep every request on the exchange, remove the fallbacks, or name only `liquid/` models:

```bash
openclaw config set agents.defaults.model.fallbacks '[]' --strict-json
```

## Troubleshooting

| Symptom                                                                        | Cause and fix                                                                                                                               |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| The install says that this release requires a newer Node.                      | Install Node 24.16 or later, then install again.                                                                                            |
| `401`                                                                          | The saved key is wrong or expired. Run the second command of step 3 again with a valid key.                                                 |
| `403`                                                                          | Check the key's `spend` scope, address restriction and preset rules.                                                                        |
| `402`                                                                          | Add credit to the workspace or raise the spend limit, then send again.                                                                      |
| OpenClaw says that `liquid` is disabled after a billing failure.               | A `402` refused a request. Add credit or raise the spend limit, then send again.                                                            |
| A turn succeeded, and no receipt shows it.                                     | A fallback model at another provider answered. See [Refusals and fallback models](#refusals-and-fallback-models).                           |
| `404`                                                                          | `plugins.entries.liquid.config.baseUrl` is set and does not end in `/v1`.                                                                   |
| OpenClaw says that the plugin needs a newer release.                           | The plugin needs OpenClaw 2026.10.5 or later. Install OpenClaw again.                                                                       |
| `openclaw config set` says that it requires exclusive offline state ownership. | A newer OpenClaw refuses a config change while a gateway runs. Run `openclaw gateway stop`, then the command, then start the gateway again. |
| The error names `no_eligible_offer`.                                           | Read `eligibility.excluded` in the error. It names the rule that each offer did not meet.                                                   |
| `cap_exceeds_buyer_cap`                                                        | Increase the request cap or select a cheaper model.                                                                                         |

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

## Next steps

- [Market data](https://inference.ai.exchange/docs/market.md): models and live offers.
- [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.