Add OpenRouter in the Models panel

Connect the key to Pi Agent

The value sk-or-v1-REDACTED is only a credential. Pi Agent cannot infer the provider endpoint, API mode, or model ID from it, so you must enter those settings explicitly.

This is a one-time setup. After Test succeeds, Pi Agent writes the provider configuration to /data/pi-agent/models.json. Return to Models when you rotate a leaked key, add another provider in Chapter 10, or update the available models.

When you finish, Models will contain a provider named OpenRouter, the model selector will include anthropic/claude-sonnet-4, and Test will show a green result. This is the repository-verified walkthrough ID; confirm that it remains available in OpenRouter’s current catalog before using it.

What the Models panel does

Recall the pi-web workspace from Chapter 4: the conversation is in the center, and the toolbar opens panels for Sessions, Skills, Models, and other controls. Models is the provider registry. It records each endpoint, credential, and model ID Pi Agent can use.

Think of it as a service directory. Each provider card is one company or gateway, and each card can list several models offered through that route.

The panel writes to /data/pi-agent/models.json when you select Save. The file is in the add-on’s persistent data area. You do not need to edit it manually. The important property is that the documented HA backup path includes it, so restoring the add-on data can restore the provider configuration. Chapter 20 covers backups.

What the three core fields mean

The Add Provider form has several controls, but three fields define the route:

All three values must match:

• Wrong endpoint, such as setting baseUrl to https://api.openai.com/v1: an OpenRouter key will not authenticate to OpenAI directly, so the request may return 401 or 404.
• Wrong credential, such as an expired apiKey or one with extra whitespace: the endpoint may return 401 Unauthorized.
• Wrong model ID, such as entering models[].name as glm-4 and omitting .6 from that historical example: the route may return 404 model not found or another model-availability error. Use the current OpenRouter ID instead.

API mode has four options: openai-completions, openai-responses, anthropic-messages, and google-generative-ai. For this OpenRouter setup, select openai-completions because the base URL exposes an OpenAI-compatible Chat Completions interface. A mismatched mode can produce a 400 or 404 response.

Eight steps to configure and test OpenRouter

Follow the controls in order. The source estimates about 3 minutes once you have the key and model details ready.

1. Open Pi Agent

   Select Pi Agent in the HA sidebar, as shown in Chapter 3. The pi-web workspace opens with the conversation area in the center and composer below.

2. Open Models

   Find Models in the top-right toolbar. Its icon may resemble a CPU or chip; use the Models tooltip to confirm it. Select it to open the drawer. On a new installation, the panel contains an Add Provider button.

3. Select Add Provider

   The form contains provider fields—Name, API mode, baseUrl, and apiKey—followed by the Models list.

4. Enter a recognizable Name

   Use OpenRouter or OpenRouter gateway. This label appears in the model selector. If you later separate home and office keys, names such as OpenRouter-home and OpenRouter-office make auditing and rotation easier.

5. Select openai-completions for API mode

   The four choices are openai-completions, openai-responses, anthropic-messages, and google-generative-ai. Choose openai-completions for this OpenRouter endpoint. A direct Anthropic configuration uses anthropic-messages; a direct Google Gemini configuration uses google-generative-ai; the newer official OpenAI endpoint can use openai-responses. See Chapter 11.

6. Enter the OpenRouter base URL

   Copy this value exactly:

   https://openrouter.ai/api/v1

   Use this exact base URL. The placeholder base URL shown above refers to the preformatted value. Use HTTPS, and do not append /chat/completions or substitute a dashboard route such as /settings/keys.

7. Paste the apiKey from Chapter 5

   Copy the key from your password manager and paste it into apiKey. The field masks the value by default; the eye control can reveal it temporarily. Check for leading or trailing whitespace. Remove any extra characters with Backspace or Delete.

8. Add an exact model catalog entry

   Select Add Model in the Models area to create a row:

   • name: enter anthropic/claude-sonnet-4, the repository-verified first model for this walkthrough. Confirm the ID in the live OpenRouter model catalog before use; if it is no longer available, choose a currently available model and copy its exact ID.
   • contextWindow: enter the model-specific value published on that model’s current details page. Do not copy a limit from another model. Chapter 9 explains context.

   Under Advanced settings, enable reasoning only if the selected model and route support it. Do not enable deepSeekThinkingCompat unless that model requires the compatibility mode, and do not set thinkingLevelMap without model-specific guidance.

   Select Test. Pi Agent sends a real request through OpenRouter. A green check mark (✔) indicates success. Select Save, then close Models.

Diagnose a failed Test

If Test shows an error instead of a green result, read its response before changing settings:

Also check these interface and Session issues:

1. Test spins for more than 30 seconds

   If networking is healthy, refresh pi-web with F5 or Ctrl+R, reopen Models, and retry. In rare cases, restart the add-on from HA → Settings → Add-ons → Pi Agent → Restart.

2. Test succeeds, but a conversation returns 401

   Confirm that the conversation uses the same model entry you tested. For example, if Models contains anthropic/claude-sonnet-4 but the selector points to “OpenRouter / glm-4,” choose the tested OpenRouter model and verify models[].name.

3. Every response is slow

   Latency varies by model, upstream provider, route, and load. Confirm baseUrl, API mode, and the model ID, then compare another appropriate model. A fixed latency threshold is not a reliable diagnosis.

4. The model selector still says “Not set”

   Select New session because an existing Session may retain its earlier model state, or refresh pi-web with F5. If the list remains empty, verify that /data/pi-agent/models.json was written.

5. The selector says “Unnamed provider”

   Open the provider card’s three-dot menu, select Edit, enter OpenRouter in Name, and save it.

Where the key is stored and backed up

These are the relevant boundaries:

• Local file: /data/pi-agent/models.json in the add-on’s persistent data area. Anyone with sufficient access to the host or add-on data can read it.
• WoowTech: The documented request path does not upload models.json to WoowTech. When you send a prompt, Pi Agent sends the credential and request content to the configured baseUrl, which is OpenRouter in this walkthrough.
• Logs: Appendix B says credentials are redacted at debug level as ***. Still review logs before sharing them.
• Migration: Create an HA backup, move its .tar file through your approved process, and restore it on the new host. The documented backup path includes keys and conversations.
• Leak response: Revoke the key in OpenRouter, create a replacement, then use Edit to update apiKey and Save.

Use two keys for the same provider

Separate OpenRouter keys can help in three situations:

• Home and office attribution: Name the cards OpenRouter-home and OpenRouter-office so usage is easier to distinguish. Follow your organization’s rules for business credentials and billing.
• Separate limits: If the dashboard offers per-key limits, different keys can apply different controls. Do not treat a key limit as a substitute for restricting HA administrator access.
• Rotation or fallback: A separately managed key can reduce disruption while you rotate another one, subject to the same account and provider limits.

To add the second key, select Add Provider again, use a different Name, keep the same baseUrl, enter the other apiKey, and add anthropic/claude-sonnet-4 only if it remains in the current catalog. Otherwise, select a currently available model and copy its exact ID. Both provider cards then appear in Models.

Edit or delete a provider

Each provider card has a three-dot menu (⋮) with two actions:

Do you need to restart Pi Agent? No. After Save, the next request uses the updated models.json configuration.

FAQ