OpenHands on one key

• OpenHands running. The local setup docs (read 2026-10-28) start it with openhands serve or one docker run, and serve the UI at http://localhost:3000:
  bashCopy

  1docker run -it --rm --pull=always \

  2 -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \

  3 -e AGENT_SERVER_IMAGE_TAG=1.26.0-python \

  4 -e LOG_ALL_EVENTS=true \

  5 -v /var/run/docker.sock:/var/run/docker.sock \

  6 -v ~/.openhands:/.openhands \

  7 -p 3000:3000 \

  8 --add-host host.docker.internal:host-gateway \

  9 --name openhands-app \

  10 docker.openhands.dev/openhands/openhands:1.8
• A RelaySwitch key. Sign in with an email code at the console. Keys start with sk-relay-. A key made for OpenHands alone keeps its spend separate on the Usage page.
• A balance. Top-ups start at $10, by card or crypto, with no subscription and no KYC. Before the first top-up the console chat gives you 12 free turns a day to try models; OpenHands requests bill the balance.

1. Open Settings (the gear icon) and the LLM tab. The first-run popup offers the same fields.
2. Turn on Advanced. The provider and model dropdowns give way to Custom Model and Base URL.
3. In Custom Model, type openai/ followed by the id exactly as the Models page shows it, for example openai/claude-sonnet-5-5. The prefix tells OpenHands to speak the OpenAI format; the display name will not work.
4. In Base URL, enter https://api.relayswitch.io/v1. Keep the /v1; OpenHands adds /chat/completions itself.
5. In API Key, paste the whole key from the console, then save.

Field names follow the OpenAI-compatible endpoint docs and the LLM settings page (both read 2026-10-28). Each save becomes an LLM profile, so keep one profile per model: change the part after openai/, save again, and switch profiles between or during conversations. The base URL and key stay the same.

Each coding model on the catalog becomes a Custom Model by putting openai/ in front of its id. These are the ones this guide prices, built from the live catalog:

Any other chat model on the Models page works the same way, including the Claude ids: they answer the OpenAI format as well as Anthropic's, so no Anthropic setting is needed.

Two curl calls rule out the key and the base URL before you debug OpenHands itself. The first lists every model id your key can call:

The second sends one small request the way OpenHands does, with the bare id and no prefix. -i prints the headers, including the request id and, on a non-streamed answer, the charge in USD.

If both work, any failure left is in the three fields. Start a conversation in OpenHands and the request shows on the console's Usage page within seconds, with its tokens and its charge.

OpenHands is an agent. Every step resends the conversation, the files it read and the command output, so input tokens are most of the bill. A low input price matters more than a low output price. Of the models here, GLM 5.3 has the lowest input rate today at $0.3178 per million tokens.

Memory condensation, on the same settings tab, summarises old events once the history passes the size you set; it trims the input tokens of a long session on any model. For the full list, with every price and context size, see the Models page. How the balance and the cached rate work is on Pricing.

The session: one feature built over 40 OpenHands steps, late enough that the context is large. Each step sends 80,000 tokens of earlier context, 2,000 new input tokens, and gets 1,500 output tokens back. Those sizes are an assumption; your own Usage page shows the real ones.

Two columns, because whether the earlier context hits the prompt cache depends on the model and the request. When it does, the response reports cached tokens and they bill at the cached rate. The console's Usage page shows the split for every request.

The spread is wide. With cache hits the same session runs $0.2904 on DeepSeek V4 Pro 0423 and $1.26 on Claude Opus 5.5. A cheap model for routine edits and a dear one for the hard step is a reasonable split; switching LLM profiles takes a few seconds, and the balance pays for both.

• 401: the key is wrong, revoked or cut short. Paste it again from the console and run the curl check.
• 402: the balance is too low for the request. Top up in the console; the key works again at once.
• 404 or a model-not-found message: the part after openai/ is not an id on the catalog. Check for a typo or a display name in place of the id.
• 429: the key hit its rate limit. Wait a minute and resend, or create a key with a higher Requests / min in the console.
• A provider error with no request on the Usage page: the openai/ prefix is missing, so OpenHands does not know which format to speak.
• Connection errors: the Base URL is missing /v1, has a typo, or a proxy or firewall blocks it. The curl check from the same machine tells you which. Inside Docker, a base URL that works on the host still needs the container to reach the internet.