name: claude-code-9router description: "Configure and run Claude Code CLI routed through 9Router Proxy (local or remote)" version: 1.0.1 author: CEO AI OS license: MIT platforms: [linux] metadata: hermes: tags: [Coding-Agent, Claude, 9Router, Proxy, Configuration, Troubleshooting] related_skills: [claude-code, codex]

Claude Code 9Router Integration Guide

This skill covers configuring and troubleshooting the Anthropic Claude Code CLI when routed through a 9Router proxy (either local or remote) instead of the standard Anthropic API endpoint.

Configuration Steps (on VPS Host)

1. Install Claude Code globally on the host VPS: bash sudo npm install -g @anthropic-ai/claude-code

2. Configure settings: Create or update ~/.claude/settings.json on the host: json { "hasCompletedOnboarding": true, "env": { "ANTHROPIC_BASE_URL": "http://127.0.0.1:20131", "ANTHROPIC_AUTH_TOKEN": "<bridge-or-9router-key>" }, "model": "sonnet" } Use a bridge root, not /v1, when the bridge appends /v1/messages itself.

3. Secure the Configuration File: Set the file permissions to 600 to prevent credentials leakage: bash chmod 600 ~/.claude/settings.json

4. Verify connection status: bash claude auth status --text It should display the bridge URL and token source.

Proxy / bridge patterns

Use the simplest method that does not require changing 9Router internals:

• Preferred: host-local bridge. Put a tiny HTTP bridge on the VPS and point Claude Code at the bridge root. The bridge can translate Anthropic-style Claude requests into the upstream 9Router/OpenAI-style request.
• Bridge endpoints to implement: HEAD /v1, GET /v1/models, POST /v1/messages, and a lightweight /health for operators.
• Avoid double-prefix paths. If Claude Code appends /v1/messages, do not set ANTHROPIC_BASE_URL to a URL that already ends in /v1.
• Model aliasing: Claude Code often behaves better with alias-style model selection such as sonnet, while the bridge returns a client-acceptable Claude model id in responses.

Pitfalls & Troubleshooting

• Git Directory Requirement: Claude Code commands will fail or timeout if run outside of a Git repository. Always ensure the working directory is initialized: bash git init
• Model Selection Errors: If Claude Code reports "There's an issue with the selected model ...", check the bridge's model response first. Returning an unsupported model id from /v1/models or /v1/messages is enough to trigger the failure even when auth is correct.
• Connectivity Probes: If Claude Code fails before making a prompt request, inspect whether it is probing HEAD /v1 or GET /v1/models. Missing those endpoints causes startup failures that look like auth/model errors.
• Verification first, not assumptions: When debugging, check claude auth status --text before changing internals. If it shows the expected base URL and token source, move on to request/endpoint validation instead of reworking Claude configuration.
• 9Router / Alibaba wiring: When the upstream provider is Alibaba DashScope behind 9Router, do not test by printing or echoing the raw key. Read DASHSCOPE_API_KEY from ~/.hermes/.env, then verify the provider by inspecting 9Router's SQLite state (/root/.9router/db/data.sqlite) or the provider UI. If 9Router already has a local API key for remote access, that is distinct from the upstream Alibaba credential; both may be required, but they should never be conflated or copied into chat output.
• Custom Base URLs (Regional Quirk): If adding a custom or regional provider (like Alibaba Singapore) fails with a 401 validation error, the proxy (9Router) might be bypassing the base URL. For 9Router to respect a custom baseUrl (e.g. for Singapore endpoint), the provider type must explicitly begin with openai-compatible- (such as openai-compatible-alibaba). If named simply openai, 9Router ignores the custom base URL and forwards to api.openai.com instead, triggering a 401 error.
• Secret-safe verification pattern: Prefer confirming provider wiring by checking rows in providerConnections and combos rather than curling /v1/models with ad-hoc auth headers in the shell. This avoids accidental key exposure and keeps troubleshooting reproducible.

Support files

• references/alibaba-9router-endpoint-quirk.md: Detailed troubleshooting recipe for configuring regional Alibaba DashScope API keys behind 9Router.
• references/proxy-architecture.md: Summarizes the host bridge, 9Router translation flow, and the exact endpoint contract Claude Code probes.