OpenCode CLIProxyAPI

Use every model exposed by CLIProxyAPI directly in OpenCode.

The plugin discovers CLIProxyAPI's live /v1/models catalog whenever OpenCode starts. Available models appear in the normal /models picker under CLIProxyAPI. OpenCode Go models that expose Anthropic-compatible endpoints are automatically routed through /v1/messages using live model metadata from models.dev; the remaining discovered models continue to use the provider's configured default protocol. No model IDs are hard-coded.

The same metadata also supplies each model's real context window (limit.context / limit.output) and its supported reasoning-effort levels, exposed as OpenCode variants (none, low, medium, high, xhigh, max, plus minimal/ultra where supported). One package supports both OpenCode v1 (plugin config key, server() entrypoint) and OpenCode v2 (plugins config key, setup() entrypoint via ctx.provider.transform).

You need OpenCode, a running CLIProxyAPI server, and one of its API keys.

opencode plugin opencode-cliproxyapi --global

Open your global OpenCode config:

~/.config/opencode/opencode.json

The installer may have created opencode.jsonc instead. Either filename works. Configure the plugin entry with your persistent server URL and API key.

On OpenCode v1:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    [
      "opencode-cliproxyapi",
      {
        "baseURL": "http://your-server:8317",
        "apiKey": "your-cli-proxy-api-key"
      }
    ]
  ]
}

On OpenCode v2 the key is plugins (plural) and options use an object. Install from npm (recommended on v2):

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": [
    {
      "package": "opencode-cliproxyapi",
      "options": {
        "baseURL": "http://your-server:8317",
        "apiKey": "your-cli-proxy-api-key"
      }
    }
  ]
}

or drop the package directory under .opencode/plugins/ for auto-discovery (a local directory referenced through the package field did not resolve under OpenCode 2.0.21 in testing; the npm and auto-discovery forms do).

The URL may include /v1, but it is not required. If baseURL is omitted, the plugin uses http://localhost:8317/v1.

Keep this global config private because it contains your API key. Do not copy the connection into a project's opencode.json or commit it to a repository.

Run a quick probe (the models CLI command does not activate location plugins, so verify with an actual run):

opencode run -m cliproxyapi/gpt-5.6-terra --title "probe" "say hi"

Variants use the provider/model#variant form:

opencode run -m cliproxyapi/gpt-5.6-terra#high --title "probe" "say hi"

Start OpenCode and run /models:

opencode

Choose CLIProxyAPI, select a model, and use OpenCode normally. Restart OpenCode whenever the model catalog on CLIProxyAPI changes.

This release stores the connection in OpenCode's global config instead of using the /connect screen. Model selection itself uses the standard /models experience.

The recommended configuration is the global plugin entry shown above:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    [
      "opencode-cliproxyapi",
      {
        "baseURL": "http://your-server:8317",
        "apiKey": "your-cli-proxy-api-key",
        "providerName": "My CLIProxyAPI"
      }
    ]
  ]
}

If model metadata cannot be reached, the plugin logs a warning and keeps the CLIProxyAPI-discovered models available with the configured default protocol.

Every discovered reasoning model gets one variant per supported effort level, taken from live models.dev reasoning_options (canonical upstream providers take precedence over mirrors). Typical sets:

Select a variant in the /models picker or cycle with the variant_cycle keybind. Models without published levels fall back to low / medium / high. Suffixed CLIProxyAPI IDs such as gemini-3.1-pro-low keep running at their suffix level by default; picking a variant overrides it for that session. Names ending in -max that are real model names (for example gpt-5.1-codex-max) are never treated as a suffix.

GPT-family models whose metadata advertises a fast-latency mode get an additional <model>-fast entry (for example gpt-5.6-terra-fast), mirroring how OpenCode core turns experimental.modes into <id>-<mode> models. The fast sibling sends service_tier: priority, which CLIProxyAPI translates to its low-latency tier. Never encode -fast into a model ID yourself on Codex/OpenAI paths: those suffixed IDs fail provider resolution (see CLIProxyAPI#2235). Synthesized siblings therefore keep the -fast selection ID but send the base model ID on the wire. If your server already lists a -fast ID, it is enriched in place and never duplicated.

Fast combines with reasoning variants: cliproxyapi/gpt-5.6-terra-fast#high sends both the priority tier and high reasoning effort. No fast siblings are created for Anthropic-routed or image models: /v1/messages has no verified fast lever, and effort variants already cover reasoning control there.

Each model is configured with the limit.context / limit.output values published by its canonical provider, so compaction and usage accounting use the real context window (for example 1050000 / 128000 for current GPT tiers, 1000000 / 128000 for Claude Sonnet). Models with no published limits keep OpenCode's defaults. Individual models can still be customized as before, and your settings take precedence over discovered values.

Environment variables remain available for containers, CI, or users who prefer not to place a key in the config:

export CLIPROXY_BASE_URL="http://your-server:8317"
export CLIPROXY_API_KEY="your-cli-proxy-api-key"

Put these lines in your shell profile if you want them to persist. Explicit plugin options in opencode.json take precedence over environment variables.

Existing provider.cliproxyapi settings are preserved, so individual models can be customized:

{
  "provider": {
    "cliproxyapi": {
      "models": {
        "gpt-5.6-terra": {
          "name": "Terra",
          "limit": {
            "context": 200000,
            "output": 65536
          }
        }
      }
    }
  }
}

Check that the global plugin entry contains a non-empty apiKey, then restart OpenCode. If you chose environment variables instead, ensure CLIPROXY_API_KEY is available to the process that starts OpenCode.

First check the API directly:

curl -H "Authorization: Bearer your-cli-proxy-api-key" \
  "http://your-server:8317/v1/models"

Then restart OpenCode and run a probe session:

opencode run -m cliproxyapi/gpt-5.6-terra --title "probe" "say hi"

Move the connection to the recommended global OpenCode config, or add the environment variables to your shell profile.

git clone https://github.com/yourcasualdev/opencode-cliproxyapi.git
cd opencode-cliproxyapi
bun install
bun run check

The repository's opencode.json loads the local build for integration testing:

bun run build
export CLIPROXY_BASE_URL="http://your-server:8317"
export CLIPROXY_API_KEY="your-cli-proxy-api-key"
opencode run -m cliproxyapi/gpt-5.6-terra --title "probe" "say hi"

See CONTRIBUTING.md for contribution guidelines and SECURITY.md for private vulnerability reporting.

MIT