Cloud model and API workflow

OpenRouter Guide

Run OpenRouter from your laptop with Claude Code, Codex CLI, Codex App, and OpenAI-compatible tools on macOS or Windows.

Guide Home Ollama Guide
Base URL: https://openrouter.ai/api/v1 Key: OPENROUTER_API_KEY Use exact OpenRouter model IDs

OpenRouter Coding Guide

This guide is only for OpenRouter cloud models and OpenAI-compatible coding applications.

0. macOS And Windows Notes

This guide works for both macOS and Windows, but commands and config paths differ.

macOS

Common shell:

text
zsh

Temporary environment variables:

bash
export OLLAMA_HOST=http://153.75.90.251:11434
export OPENROUTER_API_KEY="YOUR_OPENROUTER_API_KEY"
export OPENAI_API_KEY="$OPENROUTER_API_KEY"
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"

Remove temporary variables:

bash
unset OLLAMA_HOST
unset OPENROUTER_API_KEY
unset OPENAI_API_KEY
unset OPENAI_BASE_URL

Permanent shell aliases:

text
/Users/zarachtech/.zshrc

Claude Code settings:

text
/Users/zarachtech/.claude/settings.json

Codex config:

text
/Users/zarachtech/.codex/config.toml

Project folder example:

bash
cd ~/Documents/Codes/testglmmodel

Windows PowerShell

Use PowerShell, preferably Windows Terminal.

Temporary environment variables for the current PowerShell window:

powershell
$env:OLLAMA_HOST = "http://153.75.90.251:11434"
$env:OPENROUTER_API_KEY = "YOUR_OPENROUTER_API_KEY"
$env:OPENAI_API_KEY = $env:OPENROUTER_API_KEY
$env:OPENAI_BASE_URL = "https://openrouter.ai/api/v1"

Remove temporary variables:

powershell
Remove-Item Env:\OLLAMA_HOST -ErrorAction SilentlyContinue
Remove-Item Env:\OPENROUTER_API_KEY -ErrorAction SilentlyContinue
Remove-Item Env:\OPENAI_API_KEY -ErrorAction SilentlyContinue
Remove-Item Env:\OPENAI_BASE_URL -ErrorAction SilentlyContinue

Claude Code settings:

text
C:\Users\YOUR_WINDOWS_USERNAME\.claude\settings.json

Codex config:

text
C:\Users\YOUR_WINDOWS_USERNAME\.codex\config.toml

Project folder example:

powershell
cd C:\Users\YOUR_WINDOWS_USERNAME\Documents\Codes\testglmmodel

If a command in this guide uses export, use $env:NAME = "value" on Windows.

If a command uses unset, use Remove-Item Env:\NAME.

If a path starts with /Users/zarachtech, replace it with your Windows user path.

Windows Command Prompt

PowerShell is recommended, but Command Prompt also works.

Set variables:

bat
set OLLAMA_HOST=http://153.75.90.251:11434
set OPENROUTER_API_KEY=YOUR_OPENROUTER_API_KEY
set OPENAI_API_KEY=%OPENROUTER_API_KEY%
set OPENAI_BASE_URL=https://openrouter.ai/api/v1

Remove variables:

bat
set OLLAMA_HOST=
set OPENROUTER_API_KEY=
set OPENAI_API_KEY=
set OPENAI_BASE_URL=

SSH Tunnel On macOS

bash
ssh -L 11434:127.0.0.1:11434 root@153.75.90.251

In another terminal:

bash
export OLLAMA_HOST=http://127.0.0.1:11434
ollama list

SSH Tunnel On Windows PowerShell

Windows 10/11 usually includes OpenSSH.

powershell
ssh -L 11434:127.0.0.1:11434 root@153.75.90.251

Keep that PowerShell window open. In another PowerShell window:

powershell
$env:OLLAMA_HOST = "http://127.0.0.1:11434"
ollama list

If ssh is not found, install OpenSSH Client from:

text
Settings -> Apps -> Optional Features -> OpenSSH Client

1. OpenRouter With Claude Code And Other Applications

OpenRouter is separate from Ollama and should normally run from your laptop.

For your current setup, OpenRouter is the main workflow. The VPS/Ollama setup is secondary and only needed when you specifically want to use models installed on a VPS.

Use Ollama when:

text
Your app -> Ollama -> local MacBook model or VPS model

Use OpenRouter from your laptop when:

text
Your app -> OpenRouter API -> cloud model provider

This does not need your VPS.

OpenRouter does not use models installed on your VPS. For example, qwen2.5-coder:7b and qwen3-coder:30b installed in Ollama are not OpenRouter model IDs unless OpenRouter separately supports a model with that exact ID.

Claude Code OpenRouter Settings

Claude Code reads settings from:

text
/Users/zarachtech/.claude/settings.json

On Windows:

text
C:\Users\YOUR_WINDOWS_USERNAME\.claude\settings.json

A basic OpenRouter setup looks like this:

json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_OPENROUTER_API_KEY",
    "ANTHROPIC_API_KEY": "",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "anthropic/claude-sonnet-4.5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "anthropic/claude-opus-4.1",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "anthropic/claude-haiku-4.5"
  }
}

Use your real OpenRouter key in ANTHROPIC_AUTH_TOKEN.

Validate the JSON after editing:

bash
python3 -m json.tool /Users/zarachtech/.claude/settings.json

On Windows PowerShell, if Python is installed:

powershell
python -m json.tool C:\Users\YOUR_WINDOWS_USERNAME\.claude\settings.json

If validation fails, Claude Code may skip the whole settings file.

Switching Claude Code To A Different OpenRouter Model

Edit:

bash
nano /Users/zarachtech/.claude/settings.json

Change the model names:

json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_OPENROUTER_API_KEY",
    "ANTHROPIC_API_KEY": "",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "openai/gpt-4.1",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "google/gemini-2.5-pro",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "meta-llama/llama-3.3-70b-instruct"
  }
}

Then validate:

bash
python3 -m json.tool /Users/zarachtech/.claude/settings.json

Start Claude Code inside your project:

bash
cd /path/to/your/project
claude

Add Or Include More OpenRouter Models

OpenRouter models are selected by exact model ID. Do not guess the ID from the display name.

For example, a model may be displayed as:

text
GLM 5.2

but the actual OpenRouter model ID may look like:

text
z-ai/glm-5.2

or another provider-prefixed slug. Always copy the exact ID from:

text
https://openrouter.ai/models

Search for the model, open its model page, then copy the model ID shown by OpenRouter.

Common examples of OpenRouter model IDs:

text
anthropic/claude-sonnet-4.5
anthropic/claude-opus-4.1
openai/gpt-4.1
google/gemini-2.5-pro
z-ai/glm-4.5-air:free
z-ai/glm-5.2

If z-ai/glm-5.2 does not work, check OpenRouter's model page for the exact current ID. OpenRouter model names can change, and not every model shown elsewhere is available through OpenRouter.

Test A New OpenRouter Model Before Using It In Apps

Use this terminal test first:

bash
export OPENROUTER_API_KEY="YOUR_OPENROUTER_API_KEY"

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-ai/glm-5.2",
    "messages": [
      { "role": "user", "content": "Reply with exactly: ready" }
    ]
  }'

On Windows PowerShell:

powershell
$env:OPENROUTER_API_KEY = "YOUR_OPENROUTER_API_KEY"

curl.exe https://openrouter.ai/api/v1/chat/completions `
  -H "Authorization: Bearer $env:OPENROUTER_API_KEY" `
  -H "Content-Type: application/json" `
  -d '{ "model": "z-ai/glm-5.2", "messages": [ { "role": "user", "content": "Reply with exactly: ready" } ] }'

If the test returns model not found, use the exact model ID from OpenRouter's website.

If the test returns 402 Insufficient credits, add credits or choose a free model.

If the test returns a normal response, the model can be used in Claude Code, Codex CLI, Codex App, or other OpenAI-compatible tools.

Use GLM 5.2 With Claude Code Through OpenRouter

Edit:

bash
nano /Users/zarachtech/.claude/settings.json

On Windows:

text
C:\Users\YOUR_WINDOWS_USERNAME\.claude\settings.json

Example using GLM 5.2:

json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_OPENROUTER_API_KEY",
    "ANTHROPIC_API_KEY": "",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "z-ai/glm-5.2",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "z-ai/glm-5.2",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "z-ai/glm-5.2"
  }
}

Validate:

bash
python3 -m json.tool /Users/zarachtech/.claude/settings.json

On Windows:

powershell
python -m json.tool C:\Users\YOUR_WINDOWS_USERNAME\.claude\settings.json

Start Claude Code:

bash
cd /path/to/your/project
claude

On Windows:

powershell
cd C:\Users\YOUR_WINDOWS_USERNAME\Documents\Codes\your-project
claude

Use GLM 5.2 With Codex CLI Through OpenRouter

Make sure your Codex OpenRouter provider is configured in:

text
/Users/zarachtech/.codex/config.toml

On Windows:

text
C:\Users\YOUR_WINDOWS_USERNAME\.codex\config.toml

Then run Codex with the model:

bash
cd /path/to/your/project
export OPENROUTER_API_KEY="YOUR_OPENROUTER_API_KEY"
codex --model z-ai/glm-5.2

On Windows PowerShell:

powershell
cd C:\Users\YOUR_WINDOWS_USERNAME\Documents\Codes\your-project
$env:OPENROUTER_API_KEY = "YOUR_OPENROUTER_API_KEY"
codex --model z-ai/glm-5.2

If you want GLM 5.2 to be the default Codex model, edit:

text
/Users/zarachtech/.codex/config.toml

Set:

toml
model = "z-ai/glm-5.2"
model_provider = "openrouter"

[model_providers.openrouter]
name = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
wire_api = "responses"
env_key = "OPENROUTER_API_KEY"
env_key_instructions = "Set OPENROUTER_API_KEY in your shell environment"

Then:

bash
cd /path/to/your/project
export OPENROUTER_API_KEY="YOUR_OPENROUTER_API_KEY"
codex

Use Different OpenRouter Models Without Editing Config Every Time

For Claude Code, change the model IDs in:

text
~/.claude/settings.json

For Codex CLI, pass the model at launch:

bash
codex --model anthropic/claude-sonnet-4.5
codex --model google/gemini-2.5-pro
codex --model z-ai/glm-5.2
codex --model z-ai/glm-4.5-air:free

On Windows PowerShell, the commands are the same:

powershell
codex --model anthropic/claude-sonnet-4.5
codex --model google/gemini-2.5-pro
codex --model z-ai/glm-5.2
codex --model z-ai/glm-4.5-air:free

For other OpenAI-compatible apps, update the app's model field to the exact OpenRouter model ID.

Recommended habit:

text
1. Find exact model ID on OpenRouter.
2. Test it with curl.
3. Use it in Claude Code, Codex CLI, or your selected app.
4. If tool/file editing is weak, switch to a stronger coding-capable model.

Using Free OpenRouter Models

Some OpenRouter model IDs include :free.

Examples:

text
z-ai/glm-4.5-air:free
minimax/minimax-m2.5:free
nvidia/nemotron-3-super-120b-a12b:free

Free models can change availability, rate limits, and quality. If Claude Code returns 402 Insufficient credits, the selected model or account still requires credits.

Common OpenRouter Errors

402 Insufficient credits

text
Your OpenRouter account needs credits, or the model is not free for your account.

Fix:

text
Add credits at https://openrouter.ai/settings/credits
or switch to a free model.

400 model is not a valid model ID

text
The model name in settings.json is not recognized by OpenRouter.

Fix:

text
Use the exact model ID shown on OpenRouter.
Do not use Ollama-only model names like qwen2.5-coder:7b unless OpenRouter supports that exact ID.

Invalid or malformed JSON

text
/Users/zarachtech/.claude/settings.json has a JSON syntax error.

Fix:

bash
python3 -m json.tool /Users/zarachtech/.claude/settings.json

Then repair the line and column shown in the error.

Codex CLI With OpenRouter

Codex CLI can use custom providers from:

text
/Users/zarachtech/.codex/config.toml

Open the config:

bash
nano /Users/zarachtech/.codex/config.toml

On Windows, edit:

text
C:\Users\YOUR_WINDOWS_USERNAME\.codex\config.toml

Add or update this OpenRouter provider:

toml
model = "openai/gpt-4.1"
model_provider = "openrouter"

[model_providers.openrouter]
name = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
wire_api = "responses"
env_key = "OPENROUTER_API_KEY"
env_key_instructions = "Set OPENROUTER_API_KEY in your shell environment"

Then set your key:

bash
export OPENROUTER_API_KEY="YOUR_OPENROUTER_API_KEY"

On Windows PowerShell:

powershell
$env:OPENROUTER_API_KEY = "YOUR_OPENROUTER_API_KEY"

Start Codex in a project folder:

bash
cd /path/to/your/project
codex

On Windows PowerShell:

powershell
cd C:\Users\YOUR_WINDOWS_USERNAME\Documents\Codes\your-project
codex

Use a different OpenRouter model for one run:

bash
cd /path/to/your/project
OPENROUTER_API_KEY="YOUR_OPENROUTER_API_KEY" codex --model google/gemini-2.5-pro

On Windows PowerShell:

powershell
cd C:\Users\YOUR_WINDOWS_USERNAME\Documents\Codes\your-project
$env:OPENROUTER_API_KEY = "YOUR_OPENROUTER_API_KEY"
codex --model google/gemini-2.5-pro

Or:

bash
cd /path/to/your/project
OPENROUTER_API_KEY="YOUR_OPENROUTER_API_KEY" codex --model anthropic/claude-sonnet-4.5

Important: Codex agent workflows need strong tool/function-call behavior. If a model produces fake tool calls as text or fails to edit files, switch to a stronger model.

Codex App With OpenRouter

Codex App uses Codex configuration. Set the same OpenRouter provider in:

text
/Users/zarachtech/.codex/config.toml

Then launch:

bash
export OPENROUTER_API_KEY="YOUR_OPENROUTER_API_KEY"
codex app

On Windows PowerShell:

powershell
$env:OPENROUTER_API_KEY = "YOUR_OPENROUTER_API_KEY"
codex app

You can also open the app normally after the config is saved, but the environment variable must be available to the app process. If the app cannot see OPENROUTER_API_KEY, launch it from the terminal with the command above.

OpenCode, OpenClaw, Hermes, And Other OpenAI-Compatible Apps

Most coding apps that support OpenAI-compatible APIs need these three values:

text
API key: YOUR_OPENROUTER_API_KEY
Base URL: https://openrouter.ai/api/v1
Model: exact OpenRouter model ID

Common environment variables:

bash
export OPENROUTER_API_KEY="YOUR_OPENROUTER_API_KEY"
export OPENAI_API_KEY="$OPENROUTER_API_KEY"
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"

On Windows PowerShell:

powershell
$env:OPENROUTER_API_KEY = "YOUR_OPENROUTER_API_KEY"
$env:OPENAI_API_KEY = $env:OPENROUTER_API_KEY
$env:OPENAI_BASE_URL = "https://openrouter.ai/api/v1"

Some apps use OPENAI_BASE_URL; others use OPENAI_API_BASE, OPENAI_API_URL, or a config file. If one variable does not work, check that app's settings and use:

text
https://openrouter.ai/api/v1

as the OpenAI-compatible base URL.

Example model IDs:

text
openai/gpt-4.1
google/gemini-2.5-pro
anthropic/claude-sonnet-4.5
z-ai/glm-4.5-air:free
minimax/minimax-m2.5:free
nvidia/nemotron-3-super-120b-a12b:free

Generic app setup:

text
Provider: OpenAI-compatible / Custom OpenAI / OpenAI API
Base URL: https://openrouter.ai/api/v1
API Key: YOUR_OPENROUTER_API_KEY
Model: exact model ID from https://openrouter.ai/models

Then open the app from the project folder if it is terminal-based:

bash
cd /path/to/your/project
export OPENROUTER_API_KEY="YOUR_OPENROUTER_API_KEY"
export OPENAI_API_KEY="$OPENROUTER_API_KEY"
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"

Run the app command after that. Examples, if installed:

bash
opencode
openclaw
hermes

On Windows PowerShell, the commands are usually the same if the apps are installed and available in PATH:

powershell
opencode
openclaw
hermes

If an app asks for a model, use the exact OpenRouter ID, not an Ollama model tag. For OpenRouter, use:

text
anthropic/claude-sonnet-4.5
google/gemini-2.5-pro
openai/gpt-4.1

Do not use:

text
qwen2.5-coder:7b
qwen3-coder:30b

unless OpenRouter shows those exact model IDs in its model list.

Quick OpenRouter Test From Terminal

Use this to confirm your key and model work before configuring an app:

bash
export OPENROUTER_API_KEY="YOUR_OPENROUTER_API_KEY"

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4.1",
    "messages": [
      { "role": "user", "content": "Reply with exactly: ready" }
    ]
  }'

On Windows PowerShell:

powershell
$env:OPENROUTER_API_KEY = "YOUR_OPENROUTER_API_KEY"

curl.exe https://openrouter.ai/api/v1/chat/completions `
  -H "Authorization: Bearer $env:OPENROUTER_API_KEY" `
  -H "Content-Type: application/json" `
  -d '{ "model": "openai/gpt-4.1", "messages": [ { "role": "user", "content": "Reply with exactly: ready" } ] }'

If this fails, fix OpenRouter credits, key, or model name before changing any coding app.

Switch Between OpenRouter Apps And Ollama VPS Apps

For OpenRouter apps:

bash
unset OLLAMA_HOST
export OPENROUTER_API_KEY="YOUR_OPENROUTER_API_KEY"
export OPENAI_API_KEY="$OPENROUTER_API_KEY"
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"

On Windows PowerShell:

powershell
Remove-Item Env:\OLLAMA_HOST -ErrorAction SilentlyContinue
$env:OPENROUTER_API_KEY = "YOUR_OPENROUTER_API_KEY"
$env:OPENAI_API_KEY = $env:OPENROUTER_API_KEY
$env:OPENAI_BASE_URL = "https://openrouter.ai/api/v1"

For Ollama VPS apps:

bash
unset OPENAI_API_KEY
unset OPENAI_BASE_URL
export OLLAMA_HOST=http://153.75.90.251:11434

On Windows PowerShell:

powershell
Remove-Item Env:\OPENAI_API_KEY -ErrorAction SilentlyContinue
Remove-Item Env:\OPENAI_BASE_URL -ErrorAction SilentlyContinue
$env:OLLAMA_HOST = "http://153.75.90.251:11434"

Then launch Ollama-backed apps:

bash
ollama launch codex --model qwen2.5-coder:7b
ollama launch claude --model qwen2.5-coder:7b
ollama launch opencode --model qwen2.5-coder:7b

Switch Between OpenRouter Claude And Ollama Claude

Claude Code can be configured globally through settings.json, while ollama launch claude tries to start Claude Code with Ollama-compatible settings.

If settings.json forces OpenRouter, Claude Code may ignore the Ollama launch model and still call OpenRouter.

To use Claude Code with OpenRouter:

bash
cd /path/to/your/project
claude

To use Claude Code with Ollama cleanly, temporarily move the OpenRouter settings aside:

bash
mv /Users/zarachtech/.claude/settings.json /Users/zarachtech/.claude/settings.json.openrouter
export OLLAMA_HOST=http://153.75.90.251:11434
ollama launch claude --model qwen2.5-coder:7b

Restore OpenRouter later:

bash
mv /Users/zarachtech/.claude/settings.json.openrouter /Users/zarachtech/.claude/settings.json

If you already have a backup:

bash
cp /Users/zarachtech/.claude/settings.json.openrouter-backup /Users/zarachtech/.claude/settings.json

Use OpenRouter for Claude Code when you want stronger cloud models:

bash
cd /path/to/project
claude

Use Ollama VPS with Codex/OpenCode when you want your VPS-hosted models:

bash
cd /path/to/project
export OLLAMA_HOST=http://153.75.90.251:11434
ollama launch codex --model qwen2.5-coder:7b

Use qwen2.5-coder:7b on your VPS for stable local-style coding. Use qwen3-coder:30b only when you can tolerate slow responses on the current VPS.

Python Launcher Script

The guide folder includes a cross-platform launcher:

text
/Users/zarachtech/Downloads/llmguides/llm_launcher.py

On macOS:

bash
cd /Users/zarachtech/Downloads/llmguides
python3 llm_launcher.py

On Windows PowerShell:

powershell
cd C:\Users\YOUR_WINDOWS_USERNAME\Downloads\llmguides
python llm_launcher.py

The script saves only non-secret setup choices:

text
provider
model
app
project folder
Ollama host

It does not save OpenRouter API keys. If the current setup uses OpenRouter, it asks for the key at launch time or uses OPENROUTER_API_KEY if it already exists in the current terminal session.

Saved non-secret state is stored here:

text
~/.llm_launcher_state.json

Show the saved setup:

bash
python3 llm_launcher.py --show

On Windows:

powershell
python llm_launcher.py --show

Run the current saved setup:

bash
python3 llm_launcher.py

Change provider/model/app/project before launching:

bash
python3 llm_launcher.py --change

Preview what will run without launching anything:

bash
python3 llm_launcher.py --dry-run

If Claude Code settings contain saved ANTHROPIC_* environment overrides that interfere with the launcher, remove those overrides safely with:

bash
python3 llm_launcher.py --sanitize-claude-settings

On Windows:

powershell
python llm_launcher.py --sanitize-claude-settings

This creates a backup of the Claude settings file before removing the conflicting environment overrides.