Custom Models

Beaver can connect to custom providers such as OpenRouter, OpenAI-compatible proxies, or self-hosted HTTPS endpoints. You configure custom providers directly in Beaver's settings.

Using custom models is an advanced feature and should only be used by experienced users.

Important Warnings

If you encounter problems with a custom model, always test with a supported model first to determine if the issue is model-specific.

Model Requirements

Custom models must support the following features to work correctly with Beaver:

• Streaming: The model must support streaming responses (SSE/Server-Sent Events)
• Tool calling: The model must support function/tool calling

Models that don't support these features will not work properly with Beaver. You can confirm both with the built-in endpoint test.

Adding a Custom Provider

Provider Settings

Each provider card has the following fields:

New providers are pre-filled with OpenRouter's endpoint (https://openrouter.ai/api/v1) and the OpenAI format. To use a different provider, change the Endpoint URL and Format to match.

The endpoint is validated as you type. If it is not a valid HTTPS URL, or points to localhost or a private/internal address, the card shows an inline error and the provider stays Incomplete. See Security & Network Requirements.

Examples by Provider Type

The only differences between provider types are the Endpoint URL and Format. Use the values below as a starting point and replace the snapshot/API key with your own.

OpenAI-compatible endpoints cover most proxy servers and alternative cloud providers. Set the Endpoint URL to your provider's base URL and keep the format on OpenAI.

Anthropic-compatible endpoints use the Anthropic message format. Switch the Format dropdown to Anthropic and point the Endpoint URL at your provider.

Testing a Provider

Each provider card has a Test Endpoint button. It runs a small built-in agent (game of Rock Paper Scissors) against your provider to confirm that streaming and tool calling work end to end.

A passing test means the provider can stream responses and call tools. A failing test usually points to an incorrect endpoint, an invalid API key, or a model that does not support tool calling. However, successful tests do not guarantee that the provider will work with Beaver. See Why Beaver needs more from your API key for details.

Context Window

The context window setting is used by Beaver to trigger context compression. If 80% of the context window is reached, Beaver will attempt to compress the context to ensure the AI model can continue working effectively in the same conversation. You can artificially set this value to a lower number to trigger context compression sooner and save on costs.

However, the context window setting is not enforced as a hard limit on the total number of tokens in the conversation, and context compression is not guaranteed to sufficiently reduce the input tokens. This has two important implications:

• You can still run into an error if the input tokens exceed the actual context window of the model.
• The costs of your requests may be higher if context compression is not effective. Generally, it is best practice to frequently start new threads, which improves model responses, increases cost efficiency, and response speed.

Vision Support

By default, custom models do not support vision (images from PDF reader, area annotations). To enable vision support:

1. Turn on Supports vision in the provider card
2. Ensure your model/endpoint actually supports vision inputs

When vision is disabled:

• Images from the PDF reader and area annotations will be omitted from the prompt
• A text message will inform the model that images were shared but cannot be processed

Security & Network Requirements

All API requests are routed through Beaver's server. They are not sent directly from your computer. This architecture has important implications for custom endpoints:

• Publicly accessible endpoint required: Your Endpoint URL must be reachable from the public internet. Endpoints behind a VPN, institutional firewall, or private network will fail because Beaver's server cannot reach them.
• HTTPS required: Plain HTTP endpoints are blocked.
• No private networks: Cannot point to localhost, private IPs (10.x.x.x, 192.168.x.x, 172.16-31.x.x), or cloud metadata endpoints (169.254.x.x).

Beaver checks these rules as you type the Endpoint URL, so invalid endpoints are flagged before any request is made.

Advanced: Editing the Raw Configuration

Custom providers are stored in the beaver.customChatModels preference as a JSON array. The settings UI is the recommended way to manage them, but you can also edit this preference directly through Zotero's Config Editor.

Configuration Fields

Multiple Models Example

You can add multiple models by including multiple objects in the array:

[
  {
    "api_base": "https://openrouter.ai/api/v1",
    "format": "openai",
    "api_key": "sk-or-v1-...",
    "name": "GLM 4.6 (OpenRouter)",
    "snapshot": "z-ai/glm-4.6",
    "context_window": 200000
  },
  {
    "api_base": "https://api.example.com/v1",
    "format": "openai",
    "api_key": "your-api-key",
    "name": "Custom Provider",
    "snapshot": "llama-3-70b",
    "context_window": 8192
  },
  {
    "api_base": "https://proxy.example.com",
    "format": "anthropic",
    "api_key": "your-api-key",
    "name": "Proxied Claude",
    "snapshot": "claude-3-5-sonnet-20241022",
    "context_window": 200000,
    "supports_vision": true
  }
]