--- title: "OpenHands custom model setup on one key" canonical: https://relayswitch.io/guides/openhands generated: 2026-11-15T03:25:00.553Z source: https://api.relayswitch.io/v1/catalog base_url: https://api.relayswitch.io/v1 --- Checked 2026-10-28 # OpenHands on one key Point OpenHands at RelaySwitch through its Custom Model field: one openai/ prefix, one base URL, one prepaid key, and any coding model on the Models page billed per token. An OpenHands custom model setup is three fields behind the Advanced switch: a **Custom Model** that starts with `openai/`, a **Base URL** of `https://api.relayswitch.io/v1`, and a RelaySwitch key in **API Key**. That one entry reaches Claude, GPT, Gemini, DeepSeek, GLM and Kimi, each at the per-token price on its [model page](https://relayswitch.io/models), from a balance you top up by card or crypto. No subscription, no monthly plan to pick. This guide fills the three fields from the live catalog, lists the Custom Model string for each coding model, and prices a sample session on every one of them, so you can pick a model on cost before the agent starts. ## 01What you need - OpenHands running. The [local setup docs](https://docs.openhands.dev/usage/run-openhands/local-setup) (read 2026-10-28) start it with `openhands serve` or one `docker run`, and serve the UI at `http://localhost:3000`: bash 1`docker 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](https://app.relayswitch.io/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. ## 02OpenHands custom model settings 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. text 1`Advanced: on` 2`Custom Model: openai/claude-sonnet-5-5` 3`Base URL: https://api.relayswitch.io/v1` 4`API Key: sk-relay-...` Field names follow the [OpenAI-compatible endpoint docs](https://docs.openhands.dev/openhands/usage/llms/openai-llms) and the [LLM settings page](https://docs.openhands.dev/openhands/usage/settings/llm-settings) (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. ## 03Custom Model strings 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: text 1`openai/claude-sonnet-5-5` 2`openai/claude-opus-5-5` 3`openai/gpt-5.5` 4`openai/gpt-6.1-sol` 5`openai/gemini-3.1-pro-preview` 6`openai/deepseek-v4-pro` 7`openai/glm-5.3` 8`openai/kimi-k2.7-code` Any other chat model on the [Models page](https://relayswitch.io/models) works the same way, including the Claude ids: they answer the OpenAI format as well as Anthropic's, so no Anthropic setting is needed. ## 04Check the key before OpenHands 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: bash 1`curl https://api.relayswitch.io/v1/models -H "Authorization: Bearer sk-relay-..."` 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. bash 1`curl -i https://api.relayswitch.io/v1/chat/completions \` 2 `-H "Authorization: Bearer sk-relay-..." \` 3 `-H "Content-Type: application/json" \` 4 `-d '{"model": "claude-sonnet-5-5", "messages": [{"role": "user", "content": "Say ok."}]}'` 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. ## 05Which model to pick 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. | Model | Input | Cached | Output | Developer list in / out | Context | | --- | --- | --- | --- | --- | --- | | [Claude Sonnet 5.5](https://relayswitch.io/models/claude-sonnet-5-5) | $1.20 (40% under) | $0.075 | $3.00 (70% under) | $2.00 / $10.00 | 1M tokens | | [Claude Opus 5.5](https://relayswitch.io/models/claude-opus-5-5) | $2.716 (32% under) | $0.1455 | $9.70 (51% under) | $4.00 / $20.00 | 1M tokens | | [GPT-5.5](https://relayswitch.io/models/gpt-5.5) | $1.80 (64% under) | $0.16 | $9.00 (70% under) | $5.00 / $30.00 | 1.1M tokens | | [GPT-6.1 Sol](https://relayswitch.io/models/gpt-6.1-sol) | $0.582 (70% under) | $0.0582 | $2.91 (70% under) | $2.00 / $10.00 | 1.1M tokens | | [Gemini 3.1 Pro Preview](https://relayswitch.io/models/gemini-3.1-pro-preview) | $1.20 (40% under) | $0.12 | $7.20 (40% under) | $2.00 / $12.00 | 1M tokens | | [DeepSeek V4 Pro 0423](https://relayswitch.io/models/deepseek-v4-pro) | $0.792 (40% under) | $0.0264 | $2.376 (40% under) | $1.32 / $3.96 | 1M tokens | | [GLM 5.3](https://relayswitch.io/models/glm-5.3) | $0.3178 (70% under) | $0.066 | $0.9987 (70% under) | $1.092 / $3.432 | 1M tokens | | [Kimi K2.7 Code](https://relayswitch.io/models/kimi-k2.7-code) | $0.426 (55% under) | $0.0852 | $1.7936 (55% under) | $0.95 / $4.00 | 262K tokens | USD per million tokens, read from the RelaySwitch catalog when this page was built. Developer list: the catalog's record of the developer's own price. 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](https://relayswitch.io/models). How the balance and the cached rate work is on [Pricing](https://relayswitch.io/pricing). ## 06What a coding session costs 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. | Model | Context from cache | No cache hits | | --- | --- | --- | | [DeepSeek V4 Pro 0423](https://relayswitch.io/models/deepseek-v4-pro) | $0.2904 | $2.74 | | [GLM 5.3](https://relayswitch.io/models/glm-5.3) | $0.2964 | $1.10 | | [GPT-6.1 Sol](https://relayswitch.io/models/gpt-6.1-sol) | $0.4074 | $2.08 | | [Kimi K2.7 Code](https://relayswitch.io/models/kimi-k2.7-code) | $0.4143 | $1.50 | | [Claude Sonnet 5.5](https://relayswitch.io/models/claude-sonnet-5-5) | $0.516 | $4.12 | | [Gemini 3.1 Pro Preview](https://relayswitch.io/models/gemini-3.1-pro-preview) | $0.912 | $4.37 | | [GPT-5.5](https://relayswitch.io/models/gpt-5.5) | $1.20 | $6.44 | | [Claude Opus 5.5](https://relayswitch.io/models/claude-opus-5-5) | $1.26 | $9.49 | 40 steps at the live per-token prices. A model with no cached rate bills cached tokens at its input rate. 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. ## 07Errors and fixes - `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. ## Questions What base URL does OpenHands need for an OpenAI-compatible API? https://api.relayswitch.io/v1, with the /v1 at the end, in the Base URL field under Advanced. OpenHands appends /chat/completions to it. Why does the Custom Model start with openai/? OpenHands routes models through LiteLLM, which reads the prefix as the wire format. openai/ followed by a catalog id sends the OpenAI chat format to the base URL. Without it LiteLLM guesses the provider from the name and usually stops with a provider error. Can OpenHands use Claude through this setup? Yes. The Claude ids on RelaySwitch answer the OpenAI format as well as Anthropic's, so openai/claude-sonnet-5-5 works and bills at its price on the Models page. Does OpenHands need a subscription to use this key? No. The key draws on a prepaid balance, topped up from $10 by card or crypto, and each request bills at the live per-token price. There is no plan and no monthly fee. Is there a free API key for OpenHands? Keys are free to create, and the console chat runs 12 free turns a day before your first top-up. Requests from OpenHands bill the balance. Can the same key serve OpenHands and another editor? Yes. One key works in every OpenAI-compatible tool at once, and the Usage page shows each request. A key per tool keeps the spend of each one separate. Related - [All guides](https://relayswitch.io/guides) - [Cline](https://relayswitch.io/guides/cline) - [OpenCode](https://relayswitch.io/guides/opencode) - [Models and prices](https://relayswitch.io/models) - [How pricing works](https://relayswitch.io/pricing) - [Pay by card or crypto](https://relayswitch.io/pay-with-crypto) - [Docs](https://relayswitch.io/docs) ## Every coding model in OpenHands One key, prepaid from $10 by card or crypto. No KYC, no subscription. [Models](https://relayswitch.io/models)[Get a key](https://app.relayswitch.io/console)