Skip to content
Skip to Content
Batchwell Docs

OpenCode setup

Use Batchwell in OpenCode by adding a custom provider to ~/.config/opencode/opencode.json with settings.baseURL set to the Batchwell base URL.

To use Batchwell in OpenCode, add a custom provider under providers in ~/.config/opencode/opencode.json with the @opencode/ai/providers/openai-compatible package, settings.baseURL set to https://api.batchwell.ai/v1, your Batchwell API key read from BATCHWELL_API_KEY, and a Batchwell model id in its models map. Then set model to the provider key, a slash and the model id. This is OpenCode's documented setup for an OpenAI-compatible provider, in OpenCode 2.

Not tested end to end

This setup is not tested end to end. It follows OpenCode's documented custom provider configuration, and Batchwell has not run OpenCode against the API to confirm every feature works.

Create a key as described in the Quickstart and Authentication, then run:

Shell
curl -fsSL https://batchwell.ai/connect.sh | sh -s -- opencode --model batchwell/kimi-k3.1-pro-uncensored

It writes ~/.config/opencode/opencode.json and ~/.config/batchwell/api-key: Batchwell's provider and the model line in OpenCode's global config, and your key in a file only you can read, which the config reads with {file:...}. Every other key in opencode.json keeps its value. It reads your key from BATCHWELL_API_KEY, or asks for it on the terminal with the input hidden, and checks it with GET /v1/models before it writes anything. Then start the agent with opencode. Every file it changes is first copied to <file>.batchwell-backup-<time>; to undo it, copy that backup back over the file, or delete a file the command created. The command needs OpenCode 2 and jq, and runs on macOS, Linux and WSL; see Connect an agent for every option.

Paste this prompt into the agent, or into any coding agent, and it sets itself up the same way. It names the variable that holds the key, never the key itself, and tells the agent to back up each file before it changes it.

Prompt
Set up OpenCode to use Batchwell. Change ~/.config/opencode/opencode.json and ~/.config/batchwell/api-key.

Base URL: https://api.batchwell.ai/v1
Model id: batchwell/kimi-k3.1-pro-uncensored
API format: OpenAI Chat Completions
API key: in the environment variable BATCHWELL_API_KEY

Rules:
- Read the key from BATCHWELL_API_KEY. If it is unset, stop and ask me to export it. Never ask me to paste a key into this chat, never print it, and never write it into a file inside a git repository.
- Back up every file before you change it, as <file>.batchwell-backup-<UTC time>.
- Change only the Batchwell entries. Keep every other setting.

Steps:
- In ~/.config/opencode/opencode.json (OpenCode 2) set "model": "batchwell/batchwell/kimi-k3.1-pro-uncensored" and add providers.batchwell: package "@opencode/ai/providers/openai-compatible", settings { baseURL "https://api.batchwell.ai/v1", apiKey "{file:~/.config/batchwell/api-key}" }, models { <the model id>: {} }.
- Write ~/.config/batchwell/api-key (0600) from $BATCHWELL_API_KEY, never as a command argument.
- Check: GET https://api.batchwell.ai/v1/models with the header Authorization: Bearer $BATCHWELL_API_KEY. A 200 that lists the model id means it works.
- Tell me to restart with: opencode. The first answer comes back.

curl -fsSL https://batchwell.ai/connect.sh | sh -s -- opencode --model batchwell/kimi-k3.1-pro-uncensored does the same in one step. Guide: https://batchwell.ai/docs/clients/opencode
opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "model": "batchwell/batchwell/kimi-k3.1-pro-uncensored",
  "providers": {
    "batchwell": {
      "name": "Batchwell",
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://api.batchwell.ai/v1",
        "apiKey": "{env:BATCHWELL_API_KEY}"
      },
      "models": {
        "batchwell/kimi-k3.1-pro-uncensored": {
          "name": "Kimi K3.1 Pro (uncensored)"
        }
      }
    }
  }
}

The snippet is made for batchwell/kimi-k3.1-pro-uncensored, a model Batchwell serves today. Merge it into ~/.config/opencode/opencode.json, keeping your other keys. The key comes from the BATCHWELL_API_KEY environment variable, so no key is written into the file. Create a key as described in the Quickstart and Authentication.

OpenCode reads opencode.json as JSON or JSONC. A project's own opencode.json is merged over the global file, so a project that sets model itself keeps its own choice there.

  • model picks the model as the provider key, a slash, and the model id.
  • providers holds the provider, under the key the model reference uses before the slash.
  • package selects OpenCode's runtime for an OpenAI-compatible API, which calls the OpenAI Chat Completions API that Batchwell serves.
  • settings.baseURL is the address OpenCode sends requests to. Set it to the Batchwell base URL, which ends in /v1.
  • settings.apiKey is the bearer key OpenCode sends. {env:BATCHWELL_API_KEY} reads it from the environment. The key starts with bw_live_ or bw_test_.
  • models lists the model: the key is the model id from GET /v1/models (see models) and name is the label OpenCode shows.

OpenCode also accepts limit on each model, with the context and output token limits. Set them to the model's limits from models.

That model lists these supported parameters: temperature, top_p, max_tokens, max_completion_tokens, stop, stream_options, tools, tool_choice, reasoning_effort. These are the model's tunable parameters, not the whole request: Batchwell accepts only the fields listed under accepted fields, including stream and stream_options. Any other field fails with 400 unsupported_parameter, and the error message names the field.

Batchwell rejects n greater than 1, logprobs and top_logprobs with 400 unsupported_parameter, and accepts text content only (parts of type image_url, input_audio or file get 400 unsupported_content). The full list is on chat completions.