---
title: "OpenHands integration"
description: "Settings for using OpenHands with MiniRouter."
canonical_url: "https://minirouter.sh/docs/integrations/openhands"
markdown_url: "https://minirouter.sh/docs/integrations/openhands.md"
last_updated: "2026-09-26"
---

# OpenHands

Run the OpenHands coding agent on any MiniRouter model.

[Get a key](https://minirouter.sh/key)

[OpenHands](https://docs.openhands.dev) is an autonomous coding agent with a CLI and a web GUI. Point it at MiniRouter to run it on any tool-capable model in the [catalog](https://minirouter.sh/models), with per-key [spend limits](https://minirouter.sh/docs/rate-limits) and [guardrails](https://minirouter.sh/docs/guardrails).

> **Note:** OpenHands calls models through LiteLLM. Prefix every MiniRouter ID with `openai/`, as in `openai/zai/glm-5.3-flash`.

## Quick start

### 1. Install OpenHands

**uv**

```sh
uv tool install openhands --python 3.12
```

**Install script**

```sh
curl -fsSL https://install.openhands.dev/install.sh | sh
```

On Windows, run these inside WSL.

### 2. Create a key

[Create a key](https://minirouter.sh/key) for this agent alone.

> **Tip:** Set a daily [spend cap](https://minirouter.sh/docs/rate-limits) on it. A runaway loop then stops at that cap.

### 3. Set the model

**Settings**

In the GUI, open Settings → LLM and turn on Advanced. In the CLI, run `/settings`.

| Setting | Value |
| --- | --- |
| `Custom Model` | `openai/zai/glm-5.3-flash`. The openai/ prefix selects the OpenAI-compatible driver; everything after it is our model id, unchanged. |
| `Base URL` | `https://api.minirouter.sh/v1` |
| `API Key` | `mr-live-… (your key)` |

**Environment**

```sh
export LLM_MODEL=openai/zai/glm-5.3-flash
export LLM_BASE_URL=https://api.minirouter.sh/v1
export LLM_API_KEY=mr-live-YOUR-KEY-HERE
openhands --override-with-envs
```

> **Warning:** `LLM_MODEL` and `LLM_BASE_URL` apply only with `--override-with-envs`. Without it, OpenHands uses saved settings.

### 4. Run a task

```sh
openhands
```

Give it one task, then open [Activity](https://minirouter.sh/dashboard/activity). Each request lists its model, tokens and exact cost.

## Run headless

Headless mode runs one task with no UI. Use it in scripts and CI, or see [Automatic code review](https://minirouter.sh/docs/guides/code-review).

```sh
export LLM_MODEL=openai/zai/glm-5.3-flash
export LLM_BASE_URL=https://api.minirouter.sh/v1
export LLM_API_KEY=mr-live-YOUR-KEY-HERE
openhands --override-with-envs --headless -t "Add unit tests for utils.py"
```

| Flag | Does |
| --- | --- |
| `--headless` | No UI. Needs `-t` or `--file`. |
| `-t` | The task to run. |
| `--json` | Prints one event per line. |
| `--override-with-envs` | Uses the `LLM_*` variables. Not saved. |

> **Warning:** Headless mode approves every action. Run it in a sandbox or container.

## Use routers and presets

Put any of these in Custom Model or `LLM_MODEL`.

| Custom Model | Uses |
| --- | --- |
| `openai/minirouter/auto:code` | A model with reliable tool calling, picked by [Auto](https://minirouter.sh/docs/auto-router). |
| `openai/minirouter/fusion` | The model and effort [Fusion](https://minirouter.sh/docs/fusion) picks from the request. |
| `openai/@preset/your-slug` | Your saved models and instructions. See [Presets](https://minirouter.sh/docs/presets). |

Compare tool-capable models on [Models](https://minirouter.sh/models).

## Contain an autonomous agent

- [Spend cap](https://minirouter.sh/docs/rate-limits): Daily or monthly cap on the key.
- [Guardrail](https://minirouter.sh/docs/guardrails): Allow only the models this agent needs.
- [Activity](https://minirouter.sh/dashboard/activity): Every request with its cost.

Running several agents? Give each its own key in [Keys](https://minirouter.sh/dashboard/keys), so one runaway stops alone.

## Recommended models

| Model | Why |
| --- | --- |
| [`zai/glm-5.3-flash`](https://minirouter.sh/models/zai/glm-5.3-flash) | Best current balance of coding ability, agentic performance, context and cost. |
| [`openai/gpt-5.6-sol`](https://minirouter.sh/models/openai/gpt-5.6-sol) | Higher-intelligence option when task quality matters more than spend. |
| [`spacexai/grok-4.6`](https://minirouter.sh/models/spacexai/grok-4.6) | Strong agentic alternative with a 500K-token window. |
| [`google/gemini-3.8-flash`](https://minirouter.sh/models/google/gemini-3.8-flash) | Multimodal coding alternative with a 1M-token window. |

Browse every model in the [catalog](https://minirouter.sh/models).

## Troubleshooting

### LLM provider not found, or the model id is rejected

The openai/ prefix is doing real work — without it the underlying LiteLLM layer tries to guess a provider from the id and fails. Write openai/ followed by our id exactly: openai/zai/glm-5.3-flash.

### 404, HTML, or a parse error on every request

Almost always the base URL. Use https://api.minirouter.sh/v1 — the bare host without /v1 also works, but never append /chat/completions to the base URL field; the client adds that path itself.

Error: [400 `invalid_request`](https://minirouter.sh/docs/errors#invalid_request).

### Credits gone overnight with nothing to show

An agent in a retry loop spends at machine speed. Set dailyLimitNano on the key the agent uses — one key per agent, so a runaway is contained to that key rather than the whole balance.

Error: [402 `insufficient_credits`](https://minirouter.sh/docs/errors#insufficient_credits).

### 401 on every request

Wrong or rotated key. Keys start with mr-live-; after a rotation the old key keeps working for 24 hours, then dies.

Error: [401 `invalid_api_key`](https://minirouter.sh/docs/errors#invalid_api_key).

Every error code, with its fix: [Errors](https://minirouter.sh/docs/errors).

## Next steps

- [Guardrails](https://minirouter.sh/docs/guardrails): Budgets and model lists per key.
- [Rate limits](https://minirouter.sh/docs/rate-limits): Cap spend and requests per key.
- [Personal agents](https://minirouter.sh/use/personal-agents): Models and spend for always-on agents.