decolua/9router free AI coding tools

# 9router Configuration Pitfalls: The 5 Real Problems I Hit Connecting Claude Code and Cline to Free AI Providers

Problem Context: Why I Needed 9router

After configuring DeepSeek-TUI and LM Studio, I wanted to connect multiple AI coding tools to a unified proxy layer. 9router claims to let Claude Code, Cline, and Cursor all use free Claude/GPT/Gemini providers simultaneously.

My goal was simple: use Claude Code for coding without spending money, connected to free backends.

It took me a full day in reality.

---

Pitfall 1: SSH Key Configuration — 100 Ways to Get "Permission Denied"

The official 9router docs show SSH-style installation:

/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

But I used the HTTPS clone method, and the docs mention:

SSH errors? The marketplace clones repos via SSH. If you don't have SSH keys set up on GitHub, either add your SSH key or use the full HTTPS URL to force HTTPS cloning:

> `bash

/plugin marketplace add https://github.com/decolua/9router.git

/plugin install agent-skills@decolua-9router

> `

My actual error output:

git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.

Resolution steps:

1. Check if you have SSH public key: cat ~/.ssh/id_rsa.pub (if not, run ssh-keygen -t rsa -C "your@email")

2. Add the public key to GitHub Settings → SSH Keys

3. Or use HTTPS directly: git clone https://github.com/decolua/9router.git

On corporate networks, SSH may also be blocked by firewall — HTTPS is the only working option in that case.

---

Pitfall 2: Provider Config Order — auto-fallback Didn't Work

9router's core selling point is auto-fallback: when one provider hits rate limit or fails, it automatically switches to the next.

My initial .9router.yaml config:

providers:
  - name: anthropic
    type: claude
    api_key: ${ANTHROPIC_API_KEY}
    priority: 1
  - name: openai
    type: gpt
    api_key: ${OPENAI_API_KEY}
    priority: 2

In theory it should try Anthropic first, then fall back to OpenAI on failure.

**What actually happened:** Both failed with error RTK -40% tokens.

After digging into docs, I found out — RTK is 9router's token compression feature, and it needs to be explicitly enabled in config:

features:
  rtk_compression:
    enabled: true
    reduction_target: 0.4  # target 40% token reduction

Without this config, auto-fallback skips all requests with "incomplete provider config" error.

---

Pitfall 3: Environment Variable Loading — ${VAR} Syntax Not Being Read

I wrote many environment variable references in .9router.yaml:

providers:
  - name: anthropic
    api_key: ${ANTHROPIC_API_KEY}

Then I ran:

export ANTHROPIC_API_KEY=sk-ant-xxxxx
9router start

Result: error api_key is required, got undefined.

Root cause: 9router doesn't read shell environment variables by default. You need to explicitly enable loading:

env:
  load_from_shell: true
  variables:
    ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}

Or inject at startup:

ANTHROPIC_API_KEY=sk-ant-xxxxx 9router start --env-file .env

.env file format:

ANTHROPIC_API_KEY=sk-ant-xxxxx
OPENAI_API_KEY=sk-xxxxx

---

Pitfall 4: Claude Code's claude.ai Session Conflict with 9router

This was the nastiest one.

I was already logged into Claude Code locally (claude login), and I also wanted 9router to handle all requests.

The problem: **Claude Code defaults to api.anthropic.com, and so does 9router**. Running both simultaneously causes:

Error: 429 Too Many Requests
Rate limit exceeded for Claude API

Reason: Your Claude Code active session and 9router requests share the same API quota.

Resolution options:

Option A: Set a different API endpoint for Claude Code (in ~/.claude/settings.json):

{
  "env": {
    "ANTHROPIC_API_BASE": "https://api.anthropic.com/v1"
  }
}

Option B: Set up a request queue in 9router config to avoid concurrency:

rate_limiting:
  max_concurrent_requests: 2
  retry_after_seconds: 30

---

Pitfall 5: Windows Path Separator — Where Is .9router.yaml?

My dev machine is Windows, and 9router docs say the config file is at ~/.9router.yaml, but on Windows it's C:\Users\username\.9router.yaml.

Actual test results:

OS	Config file path
macOS/Linux	`~/.9router.yaml` or `~/.config/9router/config.yaml`
Windows	`%USERPROFILE%\.9router.yaml` or `%APPDATA%\9router\config.yaml`

Windows users can verify with PowerShell:

echo $env:USERPROFILE
# Output like: C:\Users\YourName
# Config should be at: C:\Users\YourName\.9router.yaml

If you can't find it, use this command to check which path 9router is reading:

9router config --show-path

---

Complete Working Config Template

Here's the config that finally worked for me:

# .9router.yaml
env:
  load_from_shell: true

providers:
  - name: anthropic-claude
    type: anthropic
    api_key: ${ANTHROPIC_API_KEY}
    priority: 1
    fallback:
      - openai-gpt4
      - google-gemini

  - name: openai-gpt4
    type: openai
    api_key: ${OPENAI_API_KEY}
    priority: 2

  - name: google-gemini
    type: gemini
    api_key: ${GOOGLE_API_KEY}
    priority: 3

features:
  rtk_compression:
    enabled: true
    reduction_target: 0.4

  auto_fallback:
    enabled: true
    max_retries: 3
    retry_delay_ms: 2000

rate_limiting:
  max_concurrent_requests: 2
  requests_per_minute: 60

logging:
  level: debug
  file: ./9router.log

Startup command:

export ANTHROPIC_API_KEY=sk-ant-xxxxx
export OPENAI_API_KEY=sk-xxxxx
9router start --config ~/.9router.yaml

---

Verification: Test Commands to Confirm 9router Is Working

After config is done, verify all providers are reachable:

9router health --all-providers

Expected output:

✓ anthropic-claude: OK (latency: 142ms)
✓ openai-gpt4: OK (latency: 89ms)
✓ google-gemini: OK (latency: 201ms)

If a provider shows FAILED, check:

1. Is API key loaded correctly? (echo $ANTHROPIC_API_KEY)

2. Can network reach that provider? (curl -I https://api.anthropic.com)

3. Rate limited? (429 errors need waiting or switching provider)

---

Summary: 3 Key Configuration Points

1. **Enable RTK compression**: Without rtk_compression.enabled: true, auto-fallback doesn't work

2. **Explicitly load environment variables**: Without load_from_shell: true, ${VAR} is just a literal string

3. **Windows path matters**: Windows users use %USERPROFILE%\.9router.yaml, not ~/.9router.yaml

---

Who This Is For

✅ Good for: developers managing multiple AI coding tools (Claude Code/Cline/Cursor) wanting unified management

✅ Good for: solo developers wanting to save on API costs (auto-fallback + RTK compression effects are significant)

❌ Not for: enterprise users (compliance requirements make free providers unsuitable for production code)

❌ Not for: teams needing high concurrency (>10 req/min) (shared quotas hit rate limits fast)

---

👉 Try MiniMax AI: https://platform.minimaxi.com/subscribe/token-plan?code=E5yur9NOub&source=link