OpenHands with AI Gateway

OpenHands is an open-source AI coding agent with an interactive app and headless mode. You can configure it to use AI Gateway for unified model access and spend monitoring.

Run the Vercel CLI setup command for OpenHands:

npx vercel ai-gateway setup --agent openhands

The command writes a minimal llm block into ~/.openhands/agent_settings.json pointing at the gateway with an openai/-prefixed model ID, repoints an existing condenser LLM the same way, and fills the pinned model's per-token cost fields from the gateway catalog.

If you can't use the Vercel CLI, configure OpenHands manually:

1. Create an API key

   Go to the AI Gateway section in the Vercel dashboard sidebar and click API keys to create a new API key.

2. Add the LLM block

   OpenHands keeps agent settings in ~/.openhands/agent_settings.json. Add an llm block pointing at the gateway:

   ~/.openhands/agent_settings.json

   {
     "llm": {
       "usage_id": "agent",
       "model": "openai/openai/gpt-6-astra",
       "api_key": "your-ai-gateway-api-key",
       "base_url": "https://ai-gateway.vercel.sh/coding-agent/v1"
     }
   }

   The openai/ prefix tells OpenHands to speak the OpenAI protocol; the rest is the gateway's creator/model-name slug, so openai/openai/gpt-6-astra means the gateway model openai/gpt-6-astra. The key is stored in this file, so create it with mode 0600:

   Terminal

   chmod 0600 ~/.openhands/agent_settings.json

3. Repoint the condenser LLM

   If you use a condenser for context compression, give it the same provider so its summarization calls also route through the gateway:

   ~/.openhands/agent_settings.json

   {
     "condenser": {
       "llm": {
         "model": "openai/openai/gpt-6-astra",
         "api_key": "your-ai-gateway-api-key",
         "base_url": "https://ai-gateway.vercel.sh/coding-agent/v1"
       }
     }
   }

4. Start OpenHands

   Headless runs pick this up automatically, with no --override-with-envs needed:

   Terminal

   openhands

   Switch models in /settings with openai/<gateway-model-id>.

View your usage, spend, and request activity in the AI Gateway section in the Vercel dashboard sidebar. See the observability documentation for more details.

• Browse the models catalog for available models
• Configure spend limits on your API key
• Read the OpenHands documentation for headless runs and configuration