OpenQuery/docs/api/environment-variables.md

Environment Variables

Reference for all environment variables used by OpenQuery.

📋 Summary

Variable	Purpose	Required	Default	Example
OPENROUTER_API_KEY	OpenRouter authentication	Yes	(none)	sk-or-...
OPENROUTER_MODEL	Override default LLM model	No	qwen/qwen3.5-flash-02-23	google/gemini-3-flash-preview
SEARXNG_URL	SearxNG instance URL	No	http://localhost:8002	https://searx.example.com

Detailed Reference

OPENROUTER_API_KEY

Purpose: Your OpenRouter API authentication token.

Required: Yes, unless you have ApiKey set in config file.

How to Obtain:

1. Sign up at https://openrouter.ai
2. Go to Dashboard → API Keys
3. Copy your key (starts with sk-or-)

Priority: Overrides config file ApiKey.

Setting:

# Bash/Zsh
export OPENROUTER_API_KEY="sk-or-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Fish
set -x OPENROUTER_API_KEY "sk-or-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# PowerShell
$env:OPENROUTER_API_KEY="sk-or-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Windows CMD
set OPENROUTER_API_KEY=sk-or-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Security:

• Never commit API key to version control
• Don't share key publicly
• Use environment variables or config file with restrictive permissions (600)
• Rotate key if accidentally exposed

Validation: OpenQuery checks if key is empty string and exits with error if missing:

[Error] API Key is missing. Set OPENROUTER_API_KEY environment variable or run 'configure -i' to set it up.

OPENROUTER_MODEL

Purpose: Override the default LLM model used for both query generation and final answer.

Required: No.

Default: qwen/qwen3.5-flash-02-23

Available Models (from OpenRouter):

Model	Provider	Context	Cost (Input/Output per 1M tokens)
qwen/qwen3.5-flash-02-23	Alibaba	200K	$0.10 / $0.20
qwen/qwen3.5-122b-a10b	Alibaba	200K	~$0.20 / ~$0.40
minimax/minimax-m2.5	MiniMax	200K	~$0.20 / ~$0.40
google/gemini-3-flash-preview	Google	1M	~$0.10 / ~$0.40
deepseek/deepseek-v3.2	DeepSeek	200K	~$0.10 / ~$0.30
moonshotai/kimi-k2.5	Moonshot AI	200K	~$0.10 / ~$0.30

(See OpenRouter for current pricing.)

Setting:

export OPENROUTER_MODEL="google/gemini-3-flash-preview"

Interactive Config Models: The configure -i wizard shows only these 6 models for convenience, but you can set any OpenRouter model via environment variable or non-interactive configure.

Note: Different models have different:

• Speed (Flash models faster)
• Cost (check pricing)
• Quality (may vary by task)
• Context window size (Gemini 3 Flash has 1M tokens, others ~200K)

SEARXNG_URL

Purpose: URL of the SearxNG metasearch instance.

Required: No.

Default: http://localhost:8002

Format: Must include protocol (http:// or https://) and host:port.

Setting:

# Local Docker instance
export SEARXNG_URL="http://localhost:8002"

# Remote instance with HTTPS
export SEARXNG_URL="https://searx.example.com"

# Custom port
export SEARXNG_URL="http://localhost:8080"

Finding a Public Instance:

• Visit https://searx.space for list of public instances
• Choose one with HTTPS and low latency
• Note: Public instances may have rate limits or require attribution

Priority: Overrides any default, but not config file (no config setting for SearxNG URL - only env var). Could be added to config in future.

Test Your Instance:

curl "$SEARXNG_URL/search?q=test&format=json" | head

Expected: JSON with "results": [...].

---

Configuration Priority Recap

When OpenQuery needs a value:

1. Command-line option (--model, --key from configure) - highest
2. Environment variable (OPENROUTER_MODEL, OPENROUTER_API_KEY, SEARXNG_URL)
3. Configuration file (~/.config/openquery/config: Model, ApiKey)
4. Hard-coded default (only for model)

Example:

# Config file: Model=qwen/qwen3.5-flash-02-23
export OPENROUTER_MODEL="deepseek/deepseek-v3.2"
openquery --model "google/gemini-3-flash-preview" "question"
# Uses: model=google (CLI override), overrides env and config

---

Troubleshooting Environment Variables

Variable Not Taking Effect

Symptom: openquery still uses old value after export.

Causes:

• Exported in different shell session
• Exported after running openquery
• Shell profile not reloaded

Check:

echo $OPENROUTER_API_KEY
# Should print the key (or blank if unset)

Fix:

# Export in current session
export OPENROUTER_API_KEY="sk-or-..."

# Or add to ~/.bashrc / ~/.zshrc and restart terminal

Special Characters in Values

If your API key contains special characters ($, !, etc.), quote properly:

export OPENROUTER_API_KEY='sk-or-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
# Single quotes prevent shell expansion

Variable Name Typos

OPENROUTER_API_KEY is all caps with underscores. openrouter_api_key (lowercase) won't work.

Check spelling:

env | grep -i openrouter

Windows Environment Variables

On Windows, environment variables are set per-session or user-level:

PowerShell (current session):

$env:OPENROUTER_API_KEY="sk-or-..."

Persistent (PowerShell):

[Environment]::SetEnvironmentVariable("OPENROUTER_API_KEY", "sk-or-...", "User")

CMD:

set OPENROUTER_API_KEY=sk-or-...

System Properties → Advanced → Environment Variables (GUI)

---

Next Steps

• Configuration File - Persistent configuration
• Usage Guide - How to use these variables
• Troubleshooting - Diagnose environment issues

---

Quick Reference

# Required
export OPENROUTER_API_KEY="sk-or-..."

# Optional (override defaults)
export OPENROUTER_MODEL="google/gemini-3-flash-preview"
export SEARXNG_URL="https://searx.example.com"

# Run
openquery "your question"