---
title: "OpenHands setup with one API key"
canonical: https://uplinkswitch.ai/guides/openhands
generated: 2026-11-04T08:32:47.865Z
source: https://uplinkswitch.ai/guides/openhands
base_url: https://api.uplinkswitch.com/v1
---

[›uplinkswitch](https://uplinkswitch.ai/)

[api.uplinkswitch.com/v1](https://uplinkswitch.ai/models)[Console](https://uplinkswitch.ai/console)

[›uplinkswitch](https://uplinkswitch.ai/)

# OpenHands

Advanced switch, Custom Model as openai/<id>, base URL, key. One key for every model, pay as you go.

Checked 2026-10-28

·[All guides](https://uplinkswitch.ai/guides)·[Models](https://uplinkswitch.ai/models)

At the end you have OpenHands on `https://api.uplinkswitch.com/v1` with one API key from the console and any model id on the [list](https://uplinkswitch.ai/models) in the Custom Model field, Claude included. One key, every model, pay as you go, no subscription. Each request bills per token to the balance behind that key, and the live table below is what one OpenHands step costs on each model today.

## What you need

Docker, an account on the [console](https://uplinkswitch.ai/console) with credit on it, and one key created there. Create the key for OpenHands alone, so its requests sit apart from any other tool on the Usage page. Two values go into OpenHands: the base URL, `https://api.uplinkswitch.com/v1` , and the key. Nothing is installed on the UplinkSwitch side.

Start OpenHands the way its [local setup page](https://docs.openhands.dev/usage/run-openhands/local-setup) does (read 2026-10-28), then open `http://localhost:3000`:

shell

```
docker run -it --rm --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.26.0-python \
  -e LOG_ALL_EVENTS=true \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/.openhands \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name openhands-app \
  docker.openhands.dev/openhands/openhands:1.8
```

## The settings

Click the gear icon, pick the **LLM** tab, and turn on the **Advanced** switch at the top of the page. That reveals **Custom Model** and **Base URL**, which are hidden in the basic view. OpenHands' [OpenAI proxy steps](https://docs.openhands.dev/usage/llms/openai-llms) are the same three fields (read 2026-10-28).

Settings → LLM

```
Advanced:     on
Custom Model: openai/claude-sonnet-5-5
Base URL:     https://api.uplinkswitch.com/v1
API Key:      sk-uplink-live-...
```

1.  **Custom Model**: `openai/` followed by the id. The prefix tells OpenHands to send the OpenAI chat completions format; the id after it is the one from the [Models page](https://uplinkswitch.ai/models).
2.  **Base URL**: `https://api.uplinkswitch.com/v1`, with `/v1` on the end.
3.  **API Key**: your key from the [console](https://uplinkswitch.ai/console).
4.  Save Settings.

In the CLI, `Ctrl+P` then **Settings** opens the LLM settings. An Agent Canvas LLM profile takes them on its **Advanced** tab: the model as `openai/<id>`, the base URL and the key.

## Which model to pick

Any chat id on the Models page. OpenHands needs tool calling for every file read, edit and command, and every chat model here has it, so no id on the list is a dead end. These six fit the agent:

Custom Model

```
openai/claude-sonnet-5-5
openai/claude-opus-5-5
openai/gpt-6.1-sol
openai/gemini-3.1-pro-preview
openai/deepseek-v4-pro-0813
openai/kimi-k3
```

The Claude ids answer the OpenAI format as well as the Anthropic one, so `openai/claude-sonnet-5-5` goes in the same field as `openai/gpt-6.1-sol` or `openai/deepseek-v4-pro-0813`. Input price decides the cost of a task, because OpenHands sends the conversation and every tool result back on each step; pick by the input column below. The [uncensored coding builds](https://uplinkswitch.ai/uncensored) work the same way, one id after `openai/`.

## Price per token

One OpenHands step at 40,000 input tokens and 1,500 output tokens, which is a task that has read a few files and run a command or two. Nothing is counted at the cached rate.

| Model | Input / 1M | Output / 1M | Cached input / 1M | List input | Under list | One step, 40,000 in + 1,500 out |
| --- | --- | --- | --- | --- | --- | --- |
| [Claude Sonnet 5.5](https://uplinkswitch.ai/models/claude-sonnet-5-5) | $1.20 | $3.00 | $0.075 | $2.00 | 40% on input | $0.0525 |
| [Claude Opus 5.5](https://uplinkswitch.ai/models/claude-opus-5-5) | $2.80 | $10.00 | $0.15 | $4.00 | 30% on input | $0.127 |
| [GPT-6.1 Sol](https://uplinkswitch.ai/models/gpt-6.1-sol) | $0.60 | $3.00 | $0.06 | $2.00 | 70% on input | $0.0285 |
| [Gemini 3.1 Pro Preview](https://uplinkswitch.ai/models/gemini-3.1-pro-preview) | $1.20 | $7.20 | $0.12 | $2.00 | 40% on input | $0.0588 |
| [DeepSeek V4 Pro 0813](https://uplinkswitch.ai/models/deepseek-v4-pro-0813) | $0.792 | $1.188 | $0.0625 | $1.32 | 40% on input | $0.0335 |
| [Kimi K3](https://uplinkswitch.ai/models/kimi-k3) | $0.90 | $4.50 | $0.12 | $3.00 | 70% on input | $0.0428 |

USD per million tokens, live from GET /v1/catalog. List: the developer’s own published price. The last column is the step above at this base URL, nothing at the cached rate.

Claude Sonnet 5.5 is $0.0525 for that step here, and a ten-step task is $0.525. Cached input bills at the cache-read rate in the table by itself; there is no switch to set. The [Claude Code pricing post](https://uplinkswitch.ai/blog/claude-code-api-cost) works a day and a month of agent steps at these rates.

## Check it

From a shell, the same key should list the models:

shell

```
curl https://api.uplinkswitch.com/v1/models -H "Authorization: Bearer sk-uplink-live-..."
```

Then send one request the way OpenHands does. `-i` prints the headers: `x-uplink-request-id` names the request, and on a non-streamed answer `x-uplink-charge` is what it cost in USD.

shell

```
curl -i https://api.uplinkswitch.com/v1/chat/completions \
  -H "Authorization: Bearer sk-uplink-live-..." \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-5-5", "messages": [{"role": "user", "content": "Say ok."}]}'
```

Then start a conversation in OpenHands. The request shows on the [console](https://uplinkswitch.ai/console) Usage page within seconds, with its tokens and the same charge, filterable by key and model.

## Errors you will see

-   `401 invalid_api_key`: the key is wrong or revoked. Copy it again from the console into the API Key field.
-   `402 insufficient_balance`: the balance does not cover the request. Top up in the console; the conversation resumes on the next message.
-   `402 monthly_limit_reached`: the key hit the monthly spend limit you set on it. Raise it in the console, or wait for the first of the month.
-   `404 model_not_found`: the id after `openai/` is not on the Models page at this base URL. Copy it from there rather than typing it.
-   `403 scope_denied`: the key carries a model allowlist and this id is not on it. Pick an allowed id or use a key without the limit.
-   `429 rate_limited`: the key hit its requests-per-minute or concurrency limit. The response carries `retry-after` in seconds.
-   A connection error with no status: the Base URL is missing `/v1`, or the model was typed without the `openai/` prefix. Check both fields against the block above.

## Good to know

-   Settings persist in `~/.openhands`, the volume the docker command mounts, so the model survives a restart.
-   OpenHands' configuration page lists `LLM_MODEL` and `LLM_API_KEY` as environment variables for the model and key (read 2026-10-28); the base URL is set in the Settings UI.
-   Custom Model takes one id at a time. To switch models, edit the field; Agent Canvas profiles let you keep several and pick per agent.
-   Cached input bills at the cache-read price in the table; there is nothing to set.
-   The same base URL and key go into [Cline](https://uplinkswitch.ai/guides/cline), [OpenCode](https://uplinkswitch.ai/guides/opencode) and [Claude Code](https://uplinkswitch.ai/guides/claude-code). One balance serves all of them; a key per tool keeps the spend apart.

## Questions

### 

Yes. OpenHands sends OpenAI-compatible requests through LiteLLM, and its docs give the setup as three fields under the Advanced switch: Custom Model with the openai/ prefix, Base URL and API Key (read 2026-10-28). Enter https://api.uplinkswitch.com/v1 as the Base URL and any id from the Models page after openai/.

### 

Open Settings, pick the LLM tab, turn on the Advanced switch at the top, and type the id into Custom Model as openai/<id>, for example openai/claude-sonnet-5-5. The Custom Model field only appears with Advanced on. The CLI opens its LLM settings with Ctrl+P and Settings; an Agent Canvas LLM profile takes the model, base URL and key on its Advanced tab.

### 

Yes. The Claude ids answer the OpenAI chat completions format at this base URL, so openai/claude-sonnet-5-5 and openai/claude-opus-5-5 go in Custom Model like any other id, with no Anthropic provider entry and no Anthropic key.

### 

The part after openai/ is not an id on the Models page, so the gateway returned 404 model\_not\_found. Copy the id from the Models page rather than typing it; a date suffix or a dot in the wrong place is enough to miss. The openai/ prefix itself is required: every OpenAI-compatible example in the OpenHands docs carries it.

### 

The app is open source and free; the model bills per token to whichever key you enter, and the table above is that bill with this key. One 40,000-in, 1,500-out step on Claude Sonnet 5.5 is $0.0525 here. There is no subscription: credit is prepaid, and each key can carry its own monthly spend limit.

### 

Yes. One key reaches every model from OpenHands, Cline, OpenCode, Cursor, Claude Code and your own code, and every key on the account draws on the same prepaid balance. Create a key per tool so the Usage page shows each one apart.

Get a key in the [console](https://uplinkswitch.ai/console): prepaid credit, no subscription, 30-day price lock.

## Related

-   [Claude Code pricing](https://uplinkswitch.ai/blog/claude-code-api-cost)
-   [Claude Code alternatives compared](https://uplinkswitch.ai/blog/claude-code-alternatives)
-   [Aider setup](https://uplinkswitch.ai/guides/aider)
-   [LiteLLM setup](https://uplinkswitch.ai/guides/litellm)
-   [Claude Code setup](https://uplinkswitch.ai/guides/claude-code)
-   [Claude Sonnet 5.5](https://uplinkswitch.ai/models/claude-sonnet-5-5)
-   [GPT-5.3-Codex](https://uplinkswitch.ai/models/gpt-5.3-codex)
-   [Kimi K2.7 Code](https://uplinkswitch.ai/models/kimi-k2.7-code)
-   [GLM 5.3](https://uplinkswitch.ai/models/glm-5.3)
-   [Claude API pricing](https://uplinkswitch.ai/pricing/claude)
-   [GPT API pricing](https://uplinkswitch.ai/pricing/gpt)
-   [Kimi API pricing](https://uplinkswitch.ai/pricing/kimi)
-   [GLM API pricing](https://uplinkswitch.ai/pricing/glm)