---
title: "OpenRouter Integration"
source: https://docs.autohand.ai/integrations/openrouter
---

# OpenRouter

Access Claude, GPT-4, Llama, Mistral and 200+ AI models through a unified API. Switch between providers without changing your code.

Quick answer

## What is the Autohand OpenRouter integration?

The Autohand OpenRouter integration connects the coding agent to models routed through one OpenRouter API account. It uses a single API key while keeping the chosen upstream provider and model explicit in Autohand.

Status

Available

Requires

An OpenRouter API key, account credit, and access to the selected routed model.

Configure with

Set `OPENROUTER_API_KEY`, select the `openrouter` provider, and choose a provider-qualified model ID available in OpenRouter.

Best for

Switching among hosted model providers through one API connection.

**Know before you start:** Availability, price, latency, privacy terms, and features vary by the upstream model provider and route.

## Overview

OpenRouter provides a single API to access models from multiple providers. When integrated with Autohand, you get:

-   Access to 200+ models from Anthropic, OpenAI, Google, Meta, and more
-   Automatic fallback when a model is unavailable
-   Cost optimization with model routing
-   Single API key for all providers
-   Real-time model availability and pricing

**Default provider:** OpenRouter is the default provider for Autohand CLI, giving you immediate access to the best models without additional configuration.

## Setup

Get started with OpenRouter in minutes.

### Get your API key

1.  Go to [openrouter.ai](https://openrouter.ai) and create an account
2.  Navigate to **Keys** in your dashboard
3.  Click **Create Key** and copy your API key

### Configure Autohand

Set your API key using environment variable or config file:

``` bash
# Set environment variable (recommended)
export OPENROUTER_API_KEY="sk-or-v1-xxxxxxxxxxxx"

# Or configure via CLI
autohand config set openrouter.apiKey "sk-or-v1-xxxxxxxxxxxx"
```

Verify your configuration:

``` bash
# Check current provider and model
autohand config get provider
autohand config get model

# Test with a simple prompt
autohand --prompt "Hello, which model are you?"
```

## CLI configuration

Configure OpenRouter in your `~/.autohand/config.json`:

``` json
{
  "provider": "openrouter",
  "openrouter": {
    "apiKey": "${OPENROUTER_API_KEY}",
    "model": "nvidia/nemotron-3-super-120b-a12b:free",
    "fallbackModels": [
      "anthropic/claude-3.5-sonnet",
      "openai/gpt-4o"
    ],
    "maxTokens": 4096,
    "temperature": 0.7,
    "siteUrl": "https://your-app.com",
    "siteName": "Your App"
  }
}
```

### Configuration options

| Option | Description | Default |
|---|---|---|
| apiKey | Your OpenRouter API key | - |
| model | Default model to use | nvidia/nemotron-3-super-120b-a12b:free |
| fallbackModels | Models to try if primary is unavailable | [] |
| maxTokens | Maximum tokens in response | 4096 |
| temperature | Response randomness (0-2) | 0.7 |
| siteUrl | Your app URL for rankings | - |
| siteName | Your app name for rankings | - |

## Available models

OpenRouter provides access to models from all major providers. Here are the recommended ones for coding:

### Anthropic Claude

| Model ID | Context | Best for |
|---|---|---|
| nvidia/nemotron-3-super-120b-a12b:free | 200K | Complex coding, analysis |
| anthropic/claude-3.5-sonnet | 200K | Fast, high-quality code |
| anthropic/claude-3-opus | 200K | Most capable reasoning |
| anthropic/claude-3-haiku | 200K | Quick tasks, low cost |

### OpenAI GPT

| Model ID | Context | Best for |
|---|---|---|
| openai/gpt-4o | 128K | Multimodal, fast |
| openai/gpt-4-turbo | 128K | Complex reasoning |
| openai/gpt-4o-mini | 128K | Cost-effective |
| openai/o1-preview | 128K | Advanced reasoning |

### Google Gemini

| Model ID | Context | Best for |
|---|---|---|
| google/gemini-pro-1.5 | 1M | Large context tasks |
| google/gemini-flash-1.5 | 1M | Fast, large context |

### Open-source models

| Model ID | Context | Best for |
|---|---|---|
| meta-llama/llama-3.1-405b | 128K | Most capable open model |
| meta-llama/llama-3.1-70b | 128K | Strong open model |
| mistralai/mixtral-8x22b | 64K | Efficient MoE |
| deepseek/deepseek-coder | 128K | Code generation |
| qwen/qwen-2.5-coder-32b | 128K | Multilingual code |

### Switch models

``` bash
# Set default model
autohand config set model "nvidia/nemotron-3-super-120b-a12b:free"

# Use a specific model for one session
autohand --model "openai/gpt-4o"

# Switch during a session
/model openai/gpt-4o
```

## Features

### Model fallback

Configure fallback models for automatic failover:

``` json
{
  "openrouter": {
    "model": "nvidia/nemotron-3-super-120b-a12b:free",
    "fallbackModels": [
      "anthropic/claude-3.5-sonnet",
      "openai/gpt-4o",
      "google/gemini-pro-1.5"
    ]
  }
}
```

### Cost tracking

Monitor your usage and costs:

``` bash
# View session costs
/stats

# Check account balance
curl -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  https://openrouter.ai/api/v1/auth/key
```

### Model routing

Let OpenRouter choose the best model for your query:

``` json
{
  "openrouter": {
    "model": "openrouter/auto",
    "route": "fallback"
  }
}
```

| Route | Behavior |
|---|---|
| fallback | Try models in order until one succeeds |
| cheapest | Use the cheapest available model |
| fastest | Use the fastest available model |

## Provider transforms

OpenRouter handles provider-specific features automatically:

### System prompts

System prompts are converted to the correct format for each provider:

``` json
{
  "openrouter": {
    "transforms": ["middle-out"],
    "systemPrompt": "You are an expert software engineer."
  }
}
```

### Context handling

Long conversations are automatically truncated to fit model limits:

``` json
{
  "openrouter": {
    "maxContextTokens": 100000,
    "truncateStrategy": "middle-out"
  }
}
```

## Best practices

-   **Use environment variables**: Never commit API keys to version control.
-   **Set fallback models**: Ensure availability with multiple fallback options.
-   **Match model to task**: Use Claude for coding, GPT-4o for multimodal, Gemini for large context.
-   **Monitor costs**: Check usage regularly with `/stats` command.
-   **Use site attribution**: Set `siteUrl` and `siteName` for model leaderboards.

### Recommended configurations

#### Coding tasks

``` json
{
  "openrouter": {
    "model": "nvidia/nemotron-3-super-120b-a12b:free",
    "temperature": 0.3,
    "maxTokens": 8192
  }
}
```

#### Creative tasks

``` json
{
  "openrouter": {
    "model": "anthropic/claude-3-opus",
    "temperature": 0.9,
    "maxTokens": 4096
  }
}
```

#### Large codebase analysis

``` json
{
  "openrouter": {
    "model": "google/gemini-pro-1.5",
    "maxContextTokens": 500000
  }
}
```

## Troubleshooting

### Common issues

| Issue | Solution |
|---|---|
| Invalid API key | Verify key at openrouter.ai/keys |
| Model unavailable | Configure fallback models |
| Rate limited | Add delay between requests or upgrade plan |
| Context too long | Use a model with larger context or enable truncation |
| High costs | Switch to a more cost-effective model |

### Check API status

``` bash
# List available models
curl https://openrouter.ai/api/v1/models

# Check your credits
curl -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  https://openrouter.ai/api/v1/auth/key
```

### Debug mode

``` bash
# Enable verbose logging
AUTOHAND_DEBUG=true autohand --prompt "Test"

# View request/response details
autohand --verbose
```

Common questions

## OpenRouter integration FAQ

### How do I configure the Autohand OpenRouter integration?

Set `OPENROUTER_API_KEY`, select the `openrouter` provider, and choose a provider-qualified model ID available in OpenRouter.

### What does the Autohand OpenRouter integration require?

An OpenRouter API key, account credit, and access to the selected routed model.

### What limitations should I know about?

Availability, price, latency, privacy terms, and features vary by the upstream model provider and route.