Add a custom provider to OpenCode: Capriole AI setup

With one Capriole AI API key, you can run GPT-6 Astra, Claude Fable 5.1, and Opus 5.5 in OpenCode at up to 92% less than official API prices.

What is OpenCode

OpenCode is an open-source AI coding agent available as a terminal interface, desktop app, and IDE extension. This setup adds Capriole AI as one custom provider. Each model in it uses the API protocol that Capriole AI serves for that model family.

Prerequisites

Before you begin, make sure you have:

A Capriole AI account (Sign up here)
A Premium plan (USD 9 per month, also includes unlimited web chat) or a Team plan, required for an API key (Subscribe)
A Capriole AI API key (Get your key)

Installation

OpenCode 2 and OpenCode 1 both use the opencode command, so only one of them is installed at a time. Install OpenCode 2 with the official install script:

curl -fsSL https://opencode.ai/v2/install | bash

Or install it with npm:

npm install -g @opencode/cli

To move from OpenCode 1, run opencode upgrade --major. The https://opencode.ai/install script and the opencode-ai npm package still install OpenCode 1. Verify the install:

opencode --version

Configuration

Model validation

OpenCode 2.2.5 passes a file-read and final-answer check through Capriole AI with every model in Supported models, using the OpenCode 2 configuration. OpenCode 1.19.3 passes a file-read, file-write, and final-answer check with the OpenCode 1 configuration.

OpenCode 2

Create or update ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "capriole-ai/claude-latest",
  "agents": {
    "title": {
      "model": "capriole-ai/zai/glm-5.3-flash"
    }
  },
  "providers": {
    "capriole-ai": {
      "name": "Capriole AI",
      "env": ["CAPRIOLE_AI_API_KEY"],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://api.caprioletech.com/v1"
      },
      "headers": {
        "Authorization": "Bearer {env:CAPRIOLE_AI_API_KEY}"
      },
      "models": {
        "openai-latest": {
          "name": "OpenAI latest",
          "package": "@opencode/ai/providers/openai-compatible/responses",
          "limit": {
            "context": 1050000,
            "output": 128000
          },
          "settings": {
            "reasoningEffort": "medium"
          }
        },
        "openai/gpt-6.1-sol": {
          "name": "GPT-6.1 Sol",
          "package": "@opencode/ai/providers/openai-compatible/responses",
          "limit": {
            "context": 1050000,
            "output": 128000
          },
          "settings": {
            "reasoningEffort": "medium"
          }
        },
        "claude-latest": {
          "name": "Claude latest",
          "package": "@opencode/ai/providers/anthropic-compatible",
          "limit": {
            "context": 1000000,
            "output": 128000
          }
        },
        "claude-opus-5-5": {
          "name": "Opus 5.5",
          "package": "@opencode/ai/providers/anthropic-compatible",
          "limit": {
            "context": 1000000,
            "output": 128000
          }
        },
        "google/gemini-3.8-flash": {
          "name": "Gemini 3.8 Flash",
          "limit": {
            "context": 1048576,
            "output": 65536
          }
        },
        "xai/grok-4.7": {
          "name": "Grok 4.7",
          "limit": {
            "context": 500000,
            "output": 128000
          }
        },
        "zai/glm-5.3-flash": {
          "name": "GLM 5.3 Flash",
          "limit": {
            "context": 1000000,
            "output": 128000
          }
        },
        "moonshot/kimi-k3.1-pro": {
          "name": "Kimi K3.1 Pro",
          "limit": {
            "context": 1048576,
            "output": 131072
          }
        },
        "moonshot/kimi-k3": {
          "name": "Kimi K3",
          "limit": {
            "context": 1048576,
            "output": 131072
          }
        }
      }
    }
  }
}

What each setting does:

package: "@opencode/ai/providers/openai-compatible" is the default package for the provider, so Gemini, Grok, GLM, and Kimi use Chat Completions.
Each GPT model overrides package with @opencode/ai/providers/openai-compatible/responses, which uses the Responses API. Each Claude model overrides it with @opencode/ai/providers/anthropic-compatible, which uses Anthropic Messages.
env names the variable that holds your key. The Authorization header sends the key as a Bearer token for every package. Without it, the Anthropic package sends the key in an x-api-key header, which Capriole AI does not accept.
reasoningEffort gives each GPT model a default reasoning effort. Without it, GPT models answer without reasoning.
baseURL includes /v1 for every package. limit tells OpenCode each model’s context window and output limit.
agents.title sets the model OpenCode uses for session titles.

OpenCode 1

OpenCode 1 does not read the OpenCode 2 form, but OpenCode 2 reads this one, so an OpenCode 1 setup keeps working after you upgrade. Create or update ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "capriole-ai/claude-latest",
  "small_model": "capriole-ai/zai/glm-5.3-flash",
  "provider": {
    "capriole-ai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Capriole AI",
      "options": {
        "baseURL": "https://api.caprioletech.com/v1",
        "apiKey": "{env:CAPRIOLE_AI_API_KEY}",
        "headers": {
          "Authorization": "Bearer {env:CAPRIOLE_AI_API_KEY}"
        }
      },
      "models": {
        "openai-latest": {
          "name": "OpenAI latest",
          "provider": {
            "npm": "@ai-sdk/openai"
          },
          "limit": {
            "context": 1050000,
            "output": 128000
          },
          "options": {
            "forceReasoning": true
          }
        },
        "openai/gpt-6.1-sol": {
          "name": "GPT-6.1 Sol",
          "provider": {
            "npm": "@ai-sdk/openai"
          },
          "limit": {
            "context": 1050000,
            "output": 128000
          },
          "options": {
            "forceReasoning": true
          }
        },
        "claude-latest": {
          "name": "Claude latest",
          "provider": {
            "npm": "@ai-sdk/anthropic"
          },
          "limit": {
            "context": 1000000,
            "output": 128000
          }
        },
        "claude-opus-5-5": {
          "name": "Opus 5.5",
          "provider": {
            "npm": "@ai-sdk/anthropic"
          },
          "limit": {
            "context": 1000000,
            "output": 128000
          }
        },
        "google/gemini-3.8-flash": {
          "name": "Gemini 3.8 Flash",
          "limit": {
            "context": 1048576,
            "output": 65536
          }
        },
        "xai/grok-4.7": {
          "name": "Grok 4.7",
          "limit": {
            "context": 500000,
            "output": 128000
          }
        },
        "zai/glm-5.3-flash": {
          "name": "GLM 5.3 Flash",
          "limit": {
            "context": 1000000,
            "output": 128000
          }
        },
        "moonshot/kimi-k3.1-pro": {
          "name": "Kimi K3.1 Pro",
          "limit": {
            "context": 1048576,
            "output": 131072
          }
        },
        "moonshot/kimi-k3": {
          "name": "Kimi K3",
          "limit": {
            "context": 1048576,
            "output": 131072
          }
        }
      }
    }
  }
}

What each setting does:

npm: "@ai-sdk/openai-compatible" is the default package for the provider, so Gemini, Grok, GLM, and Kimi use Chat Completions.
Each GPT model overrides provider.npm with @ai-sdk/openai, which uses the Responses API. Each Claude model overrides it with @ai-sdk/anthropic, which uses Anthropic Messages.
baseURL includes /v1 for every package.
{env:CAPRIOLE_AI_API_KEY} reads your key from the environment. The Authorization header sends it as a Bearer token for every package. Without it, the Anthropic package sends the key in an x-api-key header, which Capriole AI does not accept.
limit tells OpenCode each model’s context window and output limit, so it can track context and compact the session in time.
small_model is the model OpenCode uses for light tasks such as session titles.

Run OpenCode

Set your API key, then start OpenCode from your project directory:

export CAPRIOLE_AI_API_KEY="YOUR_CAPRIOLE_AI_API_KEY"
opencode service restart
opencode

OpenCode 2 sends model requests from a background service that reads the key when it starts, so opencode service restart picks up the key you just set. Skip it in OpenCode 1. Use /models to switch models. For a non-interactive run, use opencode run:

opencode run -m capriole-ai/claude-latest "Explain this repository."

Supported models

Model references use the form capriole-ai/<model-id>.

Model	Model ID	Protocol
OpenAI latest	`openai-latest`	Responses
GPT-6.1 Sol	`openai/gpt-6.1-sol`	Responses
Claude latest	`claude-latest`	Anthropic Messages
Opus 5.5	`claude-opus-5-5`	Anthropic Messages
Gemini 3.8 Flash	`google/gemini-3.8-flash`	Chat Completions
Grok 4.7	`xai/grok-4.7`	Chat Completions
GLM 5.3 Flash	`zai/glm-5.3-flash`	Chat Completions
Kimi K3.1 Pro	`moonshot/kimi-k3.1-pro`	Chat Completions
Kimi K3	`moonshot/kimi-k3`	Chat Completions

openai-latest and claude-latest always point to our latest flagship in each family, currently GPT-6 Astra and Claude Fable 5.1.

Troubleshooting

Why does OpenCode return an authentication error?

Confirm that CAPRIOLE_AI_API_KEY is exported in the same shell before you start OpenCode, and that the Authorization header is present under headers (OpenCode 2) or options.headers (OpenCode 1). If OpenCode 2 reports Missing Bearer token, its background service started without the key: run opencode service restart in that shell.

Why do Claude requests fail with `Unsupported Claude Messages model`?

Claude models that use the Anthropic package need the bare Claude IDs, such as claude-opus-5-5. The anthropic/-prefixed IDs are for Chat Completions.

Why do GPT requests fail?

Confirm that each GPT model has "package": "@opencode/ai/providers/openai-compatible/responses" (OpenCode 2) or "provider": { "npm": "@ai-sdk/openai" } (OpenCode 1), so its requests use the Responses API.

Why don’t Capriole AI models appear?

Confirm that the model reference uses capriole-ai/<model-id>, such as capriole-ai/moonshot/kimi-k3, and that disabled_providers does not block capriole-ai. OpenCode 1 ignores the OpenCode 2 providers form.

Why don’t config changes apply?

Check for a project-level opencode.json or an OPENCODE_CONFIG override, then restart OpenCode.

Why do provider package errors appear?

Clear ~/.cache/opencode and restart OpenCode so it reinstalls the provider packages.

Notes

Keep your key in the environment. Do not paste it into opencode.json.
To add another Capriole AI model, copy the entry of a model from the same family and change the ID. GET https://api.caprioletech.com/v1/models lists every model ID.
To use the same key with your other coding agents, see Use one API key with coding agents.
OpenCode 2 references: install, migrate from OpenCode 1, providers, models, background service, and releases.
OpenCode 1 references: install, config, providers, models, and troubleshooting.

Get started

Endpoints

Integration

Add a custom provider to OpenCode: Capriole AI setup

What is OpenCode

Prerequisites

Installation

Configuration

Model validation

OpenCode 2

OpenCode 1

Run OpenCode

Supported models

Troubleshooting

Why does OpenCode return an authentication error?

Why do Claude requests fail with `Unsupported Claude Messages model`?

Why do GPT requests fail?

Why don’t Capriole AI models appear?

Why don’t config changes apply?

Why do provider package errors appear?

Notes

What is OpenCode

Prerequisites

Installation

Configuration

Model validation

OpenCode 2

OpenCode 1

Run OpenCode

Supported models

Troubleshooting

Why does OpenCode return an authentication error?

Why do Claude requests fail with Unsupported Claude Messages model?

Why do GPT requests fail?

Why don’t Capriole AI models appear?

Why don’t config changes apply?

Why do provider package errors appear?

Notes

Why do Claude requests fail with `Unsupported Claude Messages model`?