Skip to content
Skip to Content
Batchwell Docs

OpenClaw setup

Use Batchwell in OpenClaw by adding a custom provider to ~/.openclaw/openclaw.json with baseUrl set to the Batchwell base URL.

To use Batchwell in OpenClaw, add a custom provider to ~/.openclaw/openclaw.json with baseUrl set to https://api.batchwell.ai/v1, api: "openai-completions", your Batchwell API key read from BATCHWELL_API_KEY as apiKey, and a Batchwell model id in its models list. This is OpenClaw's documented setup for an OpenAI-compatible provider.

Not tested end to end

This setup is not tested end to end. It follows OpenClaw's documented custom provider configuration, and Batchwell has not run OpenClaw 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 -- openclaw --model batchwell/kimi-k3.1-pro-uncensored

It writes ~/.openclaw/openclaw.json and ~/.openclaw/.env through OpenClaw's own CLI, and keeps your other providers and settings. 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 openclaw chat. 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 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 OpenClaw to use Batchwell. Change ~/.openclaw/openclaw.json and ~/.openclaw/.env.

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:
- With OpenClaw's own CLI, never by editing ~/.openclaw/openclaw.json by hand, add a provider "batchwell" under models.providers: baseUrl "https://api.batchwell.ai/v1", apiKey "${BATCHWELL_API_KEY}", api "openai-completions", models [{ id: <the model id> }].
- Then run openclaw models set batchwell/batchwell/kimi-k3.1-pro-uncensored. Keep every other provider and setting.
- 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: openclaw chat. The first answer comes back.

curl -fsSL https://batchwell.ai/connect.sh | sh -s -- openclaw --model batchwell/kimi-k3.1-pro-uncensored does the same in one step. Guide: https://batchwell.ai/docs/clients/openclaw
openclaw.json
{
  models: {
    mode: "merge",
    providers: {
      batchwell: {
        baseUrl: "https://api.batchwell.ai/v1",
        apiKey: "${BATCHWELL_API_KEY}",
        api: "openai-completions",
        models: [{ id: "batchwell/kimi-k3.1-pro-uncensored", name: "Kimi K3.1 Pro (uncensored)", input: ["text"] }],
      },
    },
  },
  agents: { defaults: { model: { primary: "batchwell/batchwell/kimi-k3.1-pro-uncensored" } } },
}

The snippet is made for batchwell/kimi-k3.1-pro-uncensored, a model Batchwell serves today. 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.

OpenClaw reads openclaw.json as JSON5 and validates it strictly: an unknown key stops the Gateway from starting. The Gateway watches the file and applies changes automatically.

  • mode: "merge" is the mode OpenClaw's custom provider documentation uses.
  • providers holds the provider, under the key the model reference uses before the slash.
  • baseUrl is the address OpenClaw sends requests to. Set it to the Batchwell base URL, which ends in /v1.
  • apiKey is the bearer key OpenClaw sends. ${BATCHWELL_API_KEY} reads it from the environment. The key starts with bw_live_ or bw_test_.
  • api: "openai-completions" selects the OpenAI Chat Completions API, the one Batchwell serves.
  • models lists the model: id is the model id from GET /v1/models (see models), name is the label OpenClaw shows, and input: ["text"] says the model takes text only, as Batchwell does.
  • primary under agents.defaults.model picks the model as the provider key, a slash, and the model id.

OpenClaw also accepts contextWindow and maxTokens on each model. When they are not set, it assumes 200,000 tokens of context and 32,768 output tokens. Set them to the model's limits from models if they are lower.

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.