How to Migrate from OpenRouter to Token Harbor

Migrating from OpenRouter to Token Harbor usually requires three changes:

1. Replace the API base URL.
2. Replace the API key.
3. Use the corresponding Token Harbor model ID.

If you use a supported coding agent, Token Harbor Connect can configure it automatically or guide you through the settings. If you have a custom application, you can keep the OpenAI SDK and update the client directly.

This OpenRouter migration guide covers both paths, plus testing and rollback.

Before you migrate

Keep your current OpenRouter configuration while testing Token Harbor. You will need:

• a Token Harbor account;
• a Universal Key from the dashboard;
• a model ID from the live model catalog; and
• a copy of your current OpenRouter settings.

New accounts can claim the currently available welcome credit from the dashboard. Universal Keys begin with thk_. Never put a real key in a public repository, browser application, screenshot, or support message.

Choose a migration path

• Coding agents: use Path A for Claude Code, Codex, opencode, Aider, Cursor, Cline, and other supported tools.
• Custom applications: use Path B for Python, Node.js, backends, and automations already calling OpenRouter through an OpenAI-compatible client.

Path A: Migrate a coding agent with Token Harbor Connect

Different agents store providers in different files and formats. Connect detects installed tools, backs up files it changes, and applies the appropriate setup mode.

1. Install Connect

macOS and Linux

curl -fsSL https://tokenharbor.ai/connect.sh | sh

Windows PowerShell

irm https://tokenharbor.ai/connect.ps1 | iex

Nothing needs to be installed first. If Node.js is missing, the installer provisions a private copy under ~/.tokenharbor without changing the system installation.

The menu opens after installation. Run tokenharbor in a new terminal to open it again.

2. Choose the agents

Connect uses four setup modes:

• Auto: edits the agent's configuration after creating a backup. This includes Claude Code, Codex, opencode, OpenClaw, Qwen Code, and pi.
• Env: configures shared environment variables without editing the agent's file. Aider and Hermes use this mode.
• Guided: prints the exact base URL and key for you to paste. Cursor, Cline/Roo Code, modern Continue, Zed, and several other desktop tools use this mode.
• Unsupported: explains when a client has no safe custom-gateway interface. Windsurf is currently in this category.

Legacy Continue installations using config.json may still be configured automatically. Check the current Connect documentation because client support can change.

3. Enter your Universal Key

Select all detected agents or choose them individually, then paste the Universal Key from your dashboard. Connect verifies the key before applying the configuration.

For every file it writes, Connect records the previous values and creates a one-time <file>.th-backup copy. Guided applications are not modified; finish those by pasting the displayed values into the application.

4. Restart and verify

Open a new terminal after configuration. Restart desktop editors so they reload their settings, then run:

tokenharbor status
tokenharbor doctor

Send a small request from the agent and confirm that it appears in the Token Harbor usage dashboard.

Depending on the tool, Connect may add a provider, update environment variables, or modify the agent's native configuration.

Roll back Connect

Restore all automatically managed agents with:

tokenharbor disconnect

Or restore selected agents:

tokenharbor disconnect claude codex

Connect restores only values it wrote. Settings entered manually in a guided application must also be removed manually. See the integration guides for tool-specific instructions.

Path B: Migrate a custom application

An application using the OpenAI SDK can keep the same SDK. Create a separate Token Harbor client during testing so rollback remains simple.

OpenRouter client

import os
from openai import OpenAI

openrouter_client = OpenAI(
    api_key=os.environ["OPENROUTER_API_KEY"],
    base_url="https://openrouter.ai/api/v1",
)

Token Harbor client

import os
from openai import OpenAI

token_harbor_client = OpenAI(
    api_key=os.environ["TOKEN_HARBOR_API_KEY"],
    base_url="https://tokenharbor.ai/v1",
)

response = token_harbor_client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Reply with: migration passed."}],
)

print(response.choices[0].message.content)

Set TOKEN_HARBOR_API_KEY in your secret manager or environment before running the application. This variable name is defined by the example; the Python code reads it through os.environ.

Update the model ID

OpenRouter and Token Harbor can use different IDs for the same model:

# OpenRouter
model = "deepseek/deepseek-v4-flash"

# Token Harbor
model = "deepseek-v4-flash"

Do not assume every migration only requires removing the provider prefix. Copy the exact Token Harbor ID from the model catalog, or run tokenharbor models.

If your application uses the Anthropic Messages API, Token Harbor also exposes /v1/messages. Follow the current Chat API documentation and test Anthropic-specific behavior separately.

What can differ after an OpenRouter API migration?

Both gateways provide OpenAI-compatible APIs, but gateway behavior is not necessarily identical. Test every feature your application relies on:

• streaming event handling;
• tool and function calls;
• structured output;
• context and output limits;
• provider-specific parameters;
• errors and rate limits;
• latency, token accounting, and total cost.

The same model can still produce different output because of model revisions, provider routing, parameters, and normal generation variability.

Test before switching production traffic

Use representative requests from your real workload. Confirm that authentication succeeds, the expected response fields are present, tools return valid arguments, streaming ends correctly, and usage appears in the dashboard.

Keep both clients available until the new path passes your acceptance tests. For production systems, move a small share of traffic first and retain the OpenRouter configuration as a rollback option.

Common migration issues

401 Unauthorized

Confirm that the key begins with thk_, has not been revoked, and is being read from the intended environment variable. Check for extra spaces and make sure an OpenRouter key is not being sent to Token Harbor.

Model not found

Copy the current model ID from the Token Harbor catalog. OpenRouter model slugs do not always match Token Harbor IDs.

Incorrect base URL

The OpenAI-compatible base URL is:

https://tokenharbor.ai/v1

Do not add /api. The Anthropic SDK instead uses https://tokenharbor.ai as its base URL.

Connect cannot detect an agent

Run Connect as the same operating-system user who installed the agent, then run tokenharbor doctor. Guided and unsupported tools may be listed without being automatically configured.

The agent still uses OpenRouter

Open a new terminal or restart the desktop application. Existing environment variables or cached credentials may override the new provider settings.

429 or rate-limit errors

Limits vary by gateway, route, and account. Check current usage and limits before increasing traffic.

Frequently asked questions

Can I migrate from OpenRouter without rewriting my application?

Most OpenAI-compatible applications can begin testing by changing the base URL, API key, and model ID. Verify every API feature used in production before moving traffic.

Can I keep using the OpenAI SDK?

Yes. Point the client to https://tokenharbor.ai/v1 and use a Token Harbor Universal Key.

Can Connect migrate Claude Code from OpenRouter?

Yes. Connect automatically updates Claude Code's Token Harbor base URL and key after backing up its configuration. You can also use the manual Claude Code guide.

Does Connect automatically configure Cursor, Cline, or Windsurf?

Cursor and Cline use guided setup: Connect prints the values, but you paste them into the application. Windsurf's current interface does not safely expose an arbitrary OpenAI-compatible gateway, so Connect marks it unsupported.

Create a Token Harbor API key · Browse models · Read the Quickstart