How to Use TokenAir with OpenHands: Agent Limits
TokenAir can significantly lower OpenHands model spend when repeatable agent tasks use a lower-cost model that still completes the work correctly. OpenHands accepts an OpenAI-compatible Base URL and custom model. Its tool-heavy workflow needs a separate agent test after chat works.
Compatibility verdict
Limited setup
OpenHands exposes the Custom Model, Base URL, and API Key fields needed for TokenAir. Agent reliability depends on the selected model and remains unverified through this route.
A custom endpoint path exists, but important features or request shapes need separate testing.
Before you start
- A current OpenHands installation with access to advanced LLM settings.
- A TokenAir API key and exact model ID.
- A model with enough verified context and agent capability for the task you plan to test.
Setup and compatibility steps
Step 1
Open advanced LLM settings
In OpenHands Settings, open the LLM tab and enable Advanced options so Custom Model and Base URL become available.
Step 2
Enter the TokenAir model and endpoint
Choose OpenAI as the provider, prefix the exact model ID with openai/, enter the TokenAir Base URL, and add the API key.
Step 3
Save and test basic connectivity
Save the settings and start with a short repository question. Resolve any authentication, model, or context error before attempting a longer task.
Step 4
Run one bounded agent task
Ask OpenHands to inspect a small file and make a reviewable change. Confirm tool use, the final diff, tests, retries, and total task cost.
OpenHands LLM settings to test
LLM Provider: OpenAI
Custom Model: openai/YOUR_TOKENAIR_MODEL_ID
Base URL: https://api.tokenair.ai/v1
API Key: YOUR_TOKENAIR_API_KEYReplace placeholders with values from your own TokenAir account. Never commit an API key to source control.
How to verify it
- OpenHands saves the model settings and starts without a provider error.
- The configured model returns a complete response through TokenAir.
- OpenHands uses the expected file or terminal tool and receives its result.
- The bounded task reaches a correct final state and passes its validation.
How to lower cost without hiding quality loss
TokenAir gives the client access to premium and lower-cost model choices through one OpenAI-compatible API. Savings depend on matching each task with a model that still passes review.
- Begin with a short task that has a clear completion condition and small context.
- Use a stronger model when tool reliability, long context, or recovery is more important than token price.
- Measure the whole agent run, including planning, tool loops, retries, and failed attempts.
Limits to know before production
- OpenHands warns that it requires a capable model and can have limited functionality with weaker or incompatible models.
- A TokenAir Chat Completions response does not by itself prove OpenHands tool behavior.
- Long context and repeated agent turns can outweigh a lower per-token price.
FAQ
Can OpenHands use a TokenAir OpenAI-compatible endpoint?
Yes for endpoint configuration. OpenHands documents Custom Model, Base URL, and API Key fields for OpenAI-compatible endpoints.
Why does the model use an openai/ prefix?
OpenHands uses LiteLLM provider prefixes. Keep openai/ before the exact model ID so the request uses the OpenAI-compatible path.
What should I test before an autonomous task?
Test one small task that invokes the same tools, returns a final answer, produces a reviewable diff, and passes a real validation command.
Official sources and related TokenAir docs
Tool settings change between releases. We checked these notes on July 17, 2026. Review the linked tool docs again before a production rollout.
Try one workflow before changing the default.
Use the cost checkup to choose a bounded test, then compare cost per accepted result with your current route.