# OpenCode

OpenCode is a terminal agent that accepts custom providers. The Liquid Inference provider uses the OpenAI-compatible adapter and `POST /v1/chat/completions`.

## Start with the Liquid CLI

The [Liquid CLI](https://inference.ai.exchange/docs/cli.md) starts OpenCode with the exchange as its provider. It sets the base URL, the key and the model for that process only. It writes no file of yours. Use it unless you must keep the settings in your own files.

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

Add `--model liquid.auto:cheapest` to rank the offers by price, or `--cap 0.50` to limit what one request may cost. `liquid opencode kimi/auto` runs `kimi-k3` for the main agent and `liquid.auto` for the subagents. See [Start a coding agent](https://inference.ai.exchange/docs/cli.md#start-a-coding-agent). To set up OpenCode yourself, follow the steps below.

Each `liquid opencode` session also has the [Liquid MCP server](https://inference.ai.exchange/docs/connect-mcp-server.md) with the key of the session, so the agent can buy images, speech and video. When your OpenCode config already holds a `liquid` server from `liquid mcp opencode`, the session uses that server.

## 1. Install OpenCode

Install Node.js and `jq` first. The configuration script requires `jq`.

```bash
npm install -g opencode-ai
```

## 2. Add the provider

This script adds `liquid` to `~/.config/opencode/opencode.json`. It keeps your other providers and preferences, and creates the file if it does not exist. If the file contains invalid JSON, the script stops and leaves it unchanged.

```bash
(
  set -eu
  opencode_config_dir=~/.config/opencode
  mkdir -p "$opencode_config_dir"
  touch "$opencode_config_dir/opencode.json"
  opencode_config_tmp=$(mktemp "$opencode_config_dir/opencode.json.XXXXXX")
  trap 'rm -f "$opencode_config_tmp"' EXIT
  jq --slurpfile current "$opencode_config_dir/opencode.json" '
    . as $setup | ($current[0] // {}) |
    .provider.liquid = $setup.provider.liquid |
    ."$schema" //= $setup."$schema"
  ' <<'EOF' > "$opencode_config_tmp"
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "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": "OpenCode"
        }
      },
      "models": {"liquid.auto":{}}
    }
  }
}
EOF
  mv "$opencode_config_tmp" "$opencode_config_dir/opencode.json"
)
```

The API key stays an environment reference, `{env:LIQUID_API_KEY}`. The provider sends `X-Title: OpenCode`, so receipts identify the tool.

## 3. Run it

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

Select the **Liquid Inference** provider and a model with `/models`. To select a model at start, set `model` in `opencode.json`:

```json
{ "model": "liquid/liquid.auto" }
```

Newer OpenCode releases have no `--model` flag. For one headless request, use:

```bash
opencode run 'Say ready.'
```

## Model list

OpenCode does not read `GET /v1/models`. Its model list comes from the configuration file, which holds the selected model, the router models and your workspace's presets. Run the script again after you add a preset. To print the configured names, use:

```bash
opencode models liquid
```

The CLI sorts this list by name. The exchange refuses a model name that it does not know. It never substitutes another model.

## Configuration precedence

OpenCode merges configuration files, and a later source overrides an earlier one. Project configuration can override this guide's global configuration. `OPENCODE_CONFIG_CONTENT` overrides the project configuration at runtime.

If OpenCode uses another URL or model, check the project's `opencode.json` and `.opencode` directory, `OPENCODE_CONFIG` and `OPENCODE_CONFIG_CONTENT`. See [OpenCode configuration](https://opencode.ai/docs/config/).

## Control the cost

`liquid.auto` has a cap of its own. To set the most that you accept for one request, add `x-liquid-cap-usd` to the model's `headers` in `provider.liquid.models`.

For a cap that applies to other models, add `x-liquid-cap-usd` to `provider.liquid.options.headers`. A model's header overrides the same provider header. Check both locations when you change a cap.

Each cap applies to one request. To limit total spend, set a limit on the key. See [API keys](https://inference.ai.exchange/docs/keys.md) and [Purchasing rules](https://inference.ai.exchange/docs/rules.md).

OpenCode 1.18.34 requests up to 32,000 output tokens when a custom model has no output limit. An offer must support that limit and fit within the price cap. To use a smaller limit, set the model's `limit.output`.

## Troubleshooting

| Symptom                       | Cause and fix                                                                                                   |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------- |
| The model is absent.          | Run the configuration script again after you add a preset.                                                      |
| `401`                         | Export `LIQUID_API_KEY` in the shell that starts OpenCode. Keep the environment reference in the configuration. |
| `jq` reports a parse error.   | The script requires valid JSON. OpenCode also accepts JSONC, but this script cannot edit comments.              |
| The wrong URL or cap is used. | Check project configuration, runtime overrides, and model headers.                                              |
| `output_bound_unsupported`    | Reduce `limit.output`, or select an offer that supports the requested output limit.                             |
| No offer fits the cap.        | Check the model's output limit and prices. Change the limit, cap, or model.                                     |

## Next steps

- [Pi](https://inference.ai.exchange/docs/connect-pi.md): another terminal agent with a custom provider.
- [Market data](https://inference.ai.exchange/docs/market.md): the current model names and offers.
- [Purchasing rules](https://inference.ai.exchange/docs/rules.md): request caps and service floors.