OpenRouter
OpenRouter is a unified API gateway that provides access to hundreds of AI models from leading providers like OpenAI, Anthropic, Google, Meta, Mistral, DeepSeek, xAI, and more. One API key gives you access to the full catalog.
Personas that use the openrouter provider send requests to https://openrouter.ai/api/v1 with slash-delimited model ids, for example openai/gpt-5.6-luna or anthropic/claude-sonnet-4.6.
Get an API key
Easiest path: use Home → Configure AI provider → Connect, or Settings → AI → OpenRouter → Guided setup.
- Select Connect OpenRouter.
- Sign in or create an account in your browser, then approve the connection.
- Return to Toby. It tests a short model response, securely saves the connection, and selects a model for you. The test may use a small amount of provider credit.
The approval page may identify Toby as a localhost address and port. This is the
temporary callback listener on your Mac. You do not need to copy an API key.
While waiting, use Open browser again to reopen sign-in or Cancel sign-in to stop. Sign-in expires after ten minutes. If the test reports insufficient credits, open Review pricing and account credits, add credits, then choose Retry connection test. You can retry within the same sign-in session. If it has expired, choose Start sign-in again, then reconnect.
Paste an existing key instead is always available before the model test. To revoke an issued key, use your OpenRouter keys page. Cancelling setup discards Toby’s temporary copy; it does not revoke a key that OpenRouter has already created.
Manual steps:
- Sign in at openrouter.ai.
- Open Keys (or go to openrouter.ai/keys).
- Create a new API key and copy it.
Store the key in Toby, not in shell profiles or committed files.
Configure in Toby
- Guided setup: Home checklist → Configure AI provider → Connect → Connect OpenRouter, or Settings → AI → OpenRouter → Guided setup. Toby validates the key and sets the built-in Toby persona to
openrouter/openai/gpt-5.6-luna. - Manual: Settings → AI → OpenRouter → API Key, paste your key, then set a persona’s AI Provider to
openrouter.
Toby writes the key to ~/.toby/credentials.json.
You can also set OPENROUTER_API_KEY in your environment instead of storing a key in credentials.
For any persona, set AI Provider to openrouter, then pick a model from the list or enter a custom model id.
Out of funds
If the OpenRouter account runs out of credits, Toby keeps a notice on screen until you close it. The notice names OpenRouter, says what Toby was trying to do, and includes Open Settings, which opens Settings → AI → OpenRouter. Add credits, or switch the persona to another provider, then try again.
Transcription (speech-to-text)
OpenRouter also supports speech-to-text. In Toby, open Settings → Transcription, choose OpenRouter as the provider, and pick an STT model. The model list is loaded from OpenRouter’s catalog (output_modalities=transcription) and reuses your OpenRouter chat API key when no dedicated transcription key is set.
See Transcription for setup details.
Model catalog
OpenRouter exposes a public model catalog at GET /v1/models. Toby fetches the live list automatically, even before you configure an API key, so you can browse available models in the persona editor without signing up first.
The catalog includes model names, context window sizes, pricing, and supported features. If the catalog cannot be reached, Toby falls back to a curated default list.
Recommended models
OpenRouter offers hundreds of models. These are popular choices for Toby's chat, tool use, summarization, and schedules.
Everyday chat
| Model | Role |
|---|---|
openai/gpt-5.6-luna | Fast, cost-efficient OpenAI model for high-volume chat. Default auxiliary model for OpenRouter. |
openai/gpt-5.6-terra | Balanced OpenAI model for everyday coding and reasoning. |
anthropic/claude-sonnet-4.6 | Strong all-rounder with long context and careful tool use. |
google/gemini-3-flash | Fast Google option for quick turns. |
Higher quality
| Model | Role |
|---|---|
openai/gpt-5.6-sol | Flagship OpenAI model for complex reasoning and agentic workflows. |
anthropic/claude-haiku-4.5 | Fast Anthropic model for triage-style work. |
google/gemini-3-pro | Heavier Google model for complex requests. |
Open-weight models
| Model | Role |
|---|---|
meta-llama/llama-4-maverick | Meta's larger Llama 4 variant for general-purpose work. |
deepseek/deepseek-v3.2 | Cost-effective reasoning-oriented open-weight model. |
xai/grok-4 | xAI model for experiments or comparison. |
Use Custom model in the persona editor for any model listed on OpenRouter that Toby does not show in the picker.
App attribution
Toby sends optional app attribution headers on OpenRouter requests:
| Header | Default |
|---|---|
HTTP-Referer | https://github.com/kshehadeh/toby |
X-Title | Toby |
Override with TOBY_AI_GATEWAY_REFERER / AI_GATEWAY_HTTP_REFERER or TOBY_AI_GATEWAY_APP_TITLE / AI_GATEWAY_X_TITLE.
Environment variables
| Variable | Purpose |
|---|---|
OPENROUTER_API_KEY | API key instead of configure-stored credentials |
TOBY_PRETREAT_MODEL | Override the pretreatment model (e.g. openai/gpt-5.6-luna) |
TOBY_PRETREAT_DELTA | Set to 0 to disable follow-up delta pretreatment |
See also
- AI providers overview
- Chutes — another open-source model provider
- Personas