OpenHands Custom LLM Setup

Add a TokenHub custom OpenAI-compatible model to OpenHands Advanced LLM Settings and verify a new conversation.

Create TokenHub API Key

What is OpenHands?

OpenHands is an open-source software development agent that can work with repositories, terminals, browsers, and configurable language models.

This OpenHands setup saves a TokenHub-backed LLM profile through Advanced LLM Settings. Use an OpenAI-prefixed LiteLLM model name and validate a read-only task in a new conversation before allowing changes. OpenHands routes custom models through LiteLLM, which is why the Custom Model value includes an OpenAI provider prefix as well as the exact TokenHub model ID. Saved LLM settings may not replace the profile of an existing conversation, so create a new session and validate repository reading before permitting terminal or file changes.

OpenHands resolves custom models through LiteLLM. The important step is not merely choosing “OpenAI,” but entering a provider-qualified Custom Model in the official Advanced LLM Settings. For TokenHub, use openai/YOUR_TOKENHUB_MODEL_ID.

Open Advanced LLM Settings

  1. Open LLM Settings in OpenHands.
  2. Turn on Advanced. The official Custom Model, Base URL, and API Key fields appear only in advanced settings.
  3. Enter openai/YOUR_TOKENHUB_MODEL_ID in Custom Model.
  4. Enter https://us-api.tokenhub.com/v1 in Base URL.
  5. Enter your TokenHub API key in API Key.
  6. Click Save Changes.

The openai/ prefix tells LiteLLM to use its OpenAI-compatible route. The model ID sent to TokenHub is still the value after the slash. A bare ID does not reliably tell OpenHands which LiteLLM provider to use.

Start a new Conversation after saving

OpenHands documents that LLM settings apply to new conversations by default. Restart an existing conversation if it must use the new model. For a first connection test, create a new conversation so that an old LLM profile cannot affect the result.

Test the new conversation in this order:

  1. Ask OpenHands to read and explain one file without modifying it.
  2. Check the model ID, status code, and /v1/chat/completions path in TokenHub logs.
  3. Then ask it to perform one explicit, reversible file edit or terminal command.

OpenHands also warns that it needs a capable model. If plain chat succeeds but the agent stalls at a tool step, the model may lack reliable tool calling; that does not necessarily mean the Base URL was lost.

Troubleshoot field by field

  • Model not found or a LiteLLM routing error: confirm Custom Model is openai/EXACT_MODEL_ID.
  • 401: save API Key again and do not include a Bearer prefix.
  • 404: Base URL should end in /v1, not /chat/completions.
  • Requests still use the old model: restart that conversation or create a new one.
  • Text works but tools do not: choose a TokenHub model with documented native function calling.

Official reference

Choose a compatible OpenHands model

WorkloadModel choiceWhy it fits
Complex coding tasksA tool-capable reasoning modelUse a model with reliable tool use, streaming, and the context length your workflow needs.
Daily implementationA balanced coding modelPrioritize reliable edits and useful latency for normal coding loops.
Background and subagent workA fast, lower-cost modelUse this for iterations, summaries, and simpler work only after validating tool use.
Browse TokenHub models and compatibility

OpenHands custom LLM FAQ

How do I configure a custom LLM in OpenHands?

Open Settings → LLM → Advanced, set Custom Model to openai/<TokenHub Model ID>, then enter the TokenHub /v1 Base URL and API key.

Why does the OpenHands model need an openai/ prefix?

OpenHands uses LiteLLM routing. The prefix tells LiteLLM to send the exact following model ID through an OpenAI-compatible transport.

Why did an existing OpenHands conversation keep the old model?

Saved LLM settings may not replace an existing conversation profile. Start or restart a conversation and inspect the active LLM profile.

Which models are suitable for OpenHands?

Use a coding model with reliable native tool calling and enough context for the task. A model that only chats cannot reliably operate the terminal, browser, and file tools.

How should I test OpenHands safely?

Use a test repository and start with a read-only explanation or search. Check TokenHub logs, then allow file changes and commands gradually.

References

This setup is based on TokenHub and official documentation, last verified on 2026-09-08.

Explore API setup guides for related tools and workflows.

Claude CodeAnthropic CompatibleCodexOpenAI CompatibleQwen CodeOpenAI CompatibleZCodeOpenAI / Anthropic