> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voidai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Use OpenCode with VoidAI

> Configure OpenCode V2 with a custom VoidAI Chat Completions provider, environment-variable credentials, eligible models, and tool-calling requirements.

Configure OpenCode's custom OpenAI-compatible provider to send [Chat Completions](/api-reference/chat/completions) requests to VoidAI.

<Note>
  This configuration follows the official OpenCode V2 documentation, checked on October 1, 2026, when `@opencode/cli` was version `2.0.21`. An end-to-end OpenCode integration with VoidAI has not been run. Model and provider behavior can vary.
</Note>

## Before you configure OpenCode

Use an existing OpenCode installation and a VoidAI API key available to its process as `VOIDAI_API_KEY`. See [authentication](/authentication) if you need a key.

Choose an exact model `id` from the [VoidAI catalog](/api-reference/models/list). For this guide, the model must advertise `/v1/chat/completions` in `endpoints`, with `supports_streaming` and `supports_tool_calling` enabled. Your account must also satisfy its plan and access requirements and have sufficient credits. Catalog visibility alone does not establish eligibility or guarantee provider availability.

If you choose a Claude model, an additional account access grant is required. Read the [Claude access and usage checks](/api-reference/messages/create#claude-access-and-usage-checks), which also apply when Claude is called through Chat Completions.

## Configure OpenCode V2

Create or merge this configuration into your project's `opencode.json`. Replace `REPLACE_WITH_EXACT_MODEL_ID` with the selected VoidAI model ID before starting a session.

```json theme={null}
{
  "model": "voidai/coding",
  "providers": {
    "voidai": {
      "name": "VoidAI",
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://api.voidai.app/v1",
        "apiKey": "{env:VOIDAI_API_KEY}"
      },
      "models": {
        "coding": {
          "modelID": "REPLACE_WITH_EXACT_MODEL_ID",
          "name": "VoidAI coding model",
          "capabilities": {
            "tools": true,
            "input": ["text"],
            "output": ["text"]
          }
        }
      }
    }
  }
}
```

`voidai/coding` is OpenCode's local model selection: `voidai` is the provider ID and `coding` is the configured alias. `modelID` is the exact identifier sent to VoidAI. The base URL includes `/v1`; do not append `/chat/completions` to it.

The `{env:VOIDAI_API_KEY}` expression reads the credential from the environment. Make it available to the OpenCode process or server that sends requests, and keep the actual key out of the configuration file. In the model picker, select `voidai/coding`; `/models` shows the models you configured.

The `tools` capability tells OpenCode to use tools. It does not add tool support to a model. This example declares text input and output; enable other modalities only when supported by your chosen route and model.

OpenCode's official [V2 provider configuration](https://opencode.ai/v2/docs/providers) and [model configuration](https://opencode.ai/v2/docs/models) describe these fields.

## Set model limits deliberately

When the selected catalog entry supplies `max_context_tokens` and `max_output_tokens`, use those values for `providers.voidai.models.coding.limit.context` and `limit.output`. These are numeric token limits, not prices. Check any additional provider constraints before choosing a larger request budget.

The example leaves limits unset because they vary by model. OpenCode uses fallback limits for an unknown custom model; those defaults are not a measurement of VoidAI's limits. If the catalog omits a limit, confirm it before relying on OpenCode's remaining-context display. See the official [custom-model defaults](https://opencode.ai/v2/docs/models#aliases).

## Chat, Responses, and tools

This setup chooses the OpenAI-compatible Chat runtime. OpenCode documents a separate `@opencode/ai/providers/openai-compatible/responses` runtime for Responses. VoidAI exposing [Responses](/api-reference/responses/create) does not establish that every OpenCode Responses feature works with every model. Keep this guide's package and Chat endpoint together.

OpenCode sends tool definitions and handles tool execution in its own environment. VoidAI returns model output and tool-call requests. Tool schemas, streamed arguments, follow-up tool results, and optional reasoning behavior still depend on the selected model and provider. See the separate [tool-calling walkthrough](/guides/tool-calling) for the request/result cycle.

## OpenCode V1.18.x

Use this separate configuration if you are running OpenCode V1.18.x, including `opencode-ai` version `1.18.34`. V1 uses `provider`, `npm`, `options`, and model `id`. Apply the same prerequisites and model-limit checks above.

```json theme={null}
{
  "$schema": "https://opencode.ai/config.json",
  "model": "voidai/coding",
  "provider": {
    "voidai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "VoidAI",
      "options": {
        "baseURL": "https://api.voidai.app/v1",
        "apiKey": "{env:VOIDAI_API_KEY}"
      },
      "models": {
        "coding": {
          "id": "REPLACE_WITH_EXACT_MODEL_ID",
          "name": "VoidAI coding model",
          "tool_call": true,
          "modalities": {
            "input": ["text"],
            "output": ["text"]
          }
        }
      }
    }
  }
}
```

In V1, optional limits go under `provider.voidai.models.coding.limit`. Use `@ai-sdk/openai-compatible` for Chat Completions; OpenCode's [V1 provider guide](https://opencode.ai/docs/providers/#custom-provider) distinguishes it from the Responses package.

Do not combine V1 and V2 fields inside a provider or model entry. OpenCode's [migration guide](https://opencode.ai/v2/docs/migrate-v1/) explains its support for existing V1 configurations and the native V2 format.

## Troubleshooting

* **Provider or model missing:** check your OpenCode version, configuration location, and the `voidai/coding` selection. A custom provider needs an explicit model entry.
* **401:** confirm `VOIDAI_API_KEY` reaches the process sending requests and review [authentication](/authentication).
* **403 or access denied:** check account eligibility, credits, and any Claude access grant. Adding a model to OpenCode does not grant API access.
* **404 or unknown model:** check the exact upstream model ID, `/v1` base URL, and the model's advertised [endpoints](/api-reference/models/list).
* **Tool, streaming, or validation error:** check the selected model's capability flags and provider constraints. Declaring a capability in OpenCode cannot make an unsupported request succeed.

For rate limits and provider failures, follow [API error handling](/guides/errors). OpenCode's token or cost display is not authoritative for VoidAI billing; use [credits and caching](/guides/credits) and your account usage.