ClaudeCode-Custom-Skills/skills/openrouter-config/README.md

# OpenRouter Config Skill

## Description
This skill helps users configure and enable OpenRouter as the AI provider in Claude Code. It sets up the OpenRouter API key, configures the Anthropic-compatible API endpoints, and ensures Claude Code uses OpenRouter exclusively with proper failover capabilities.

## Documentation Source
Based on official OpenRouter documentation: https://openrouter.ai/docs/guides/claude-code-integration

## Why Use OpenRouter with Claude Code?

### 1. Provider Failover for High Availability
Anthropic's API occasionally experiences outages or rate limiting. When you route Claude Code through OpenRouter, your requests automatically fail over between multiple Anthropic providers. If one provider is unavailable or rate-limited, OpenRouter seamlessly routes to another, keeping your coding sessions uninterrupted.

### 2. Organizational Budget Controls
For teams and organizations, OpenRouter provides centralized budget management. You can set spending limits, allocate credits across team members, and prevent unexpected cost overruns.

### 3. Usage Visibility and Analytics
OpenRouter gives you complete visibility into how Claude Code is being used across your team. Track usage patterns, monitor costs in real-time, and understand which projects or team members are consuming the most resources. All of this data is available in your [OpenRouter Activity Dashboard](https://openrouter.ai/dashboard/activity).

## Usage
To use this skill, simply ask Claude Code to configure OpenRouter. The skill will:
1. Set up your OpenRouter API key
2. Configure the Anthropic-compatible environment variables
3. Ensure Claude Code uses OpenRouter exclusively
4. Set up proper provider priority (Anthropic 1P)
5. Verify the configuration is working

## Prerequisites
- An OpenRouter API key (get one from https://openrouter.ai/keys)
- Claude Code installed

## Configuration Steps

### Step 1: Install Claude Code (if not already installed)
```bash
# macOS, Linux, WSL:
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell:
irm https://claude.ai/install.ps1 | iex
```

### Step 2: Configure Environment Variables
The skill will help you set these environment variables in your shell profile:

```bash
# Add to ~/.zshrc (or ~/.bashrc for Bash, ~/.config/fish/config.fish for Fish)
export OPENROUTER_API_KEY="<your-openrouter-api-key>"
export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
export ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY"
export ANTHROPIC_API_KEY="" # Important: Must be explicitly empty
```

**Important Notes:**
- **Do NOT** put these in a project-level `.env` file - the native Claude Code installer does not read standard `.env` files
- **Must explicitly blank out** `ANTHROPIC_API_KEY` to prevent conflicts
- If previously logged in to Claude Code with Anthropic, run `/logout` in a Claude Code session to clear cached credentials

### Step 3: Start Claude Code
```bash
cd /path/to/your/project
claude
```

### Step 4: Verify Configuration
Run the `/status` command inside Claude Code:
```
/status
```

Expected output:
```
Auth token: ANTHROPIC_AUTH_TOKEN
Anthropic base URL: https://openrouter.ai/api
```

You can also check the [OpenRouter Activity Dashboard](https://openrouter.ai/dashboard/activity) to see your requests appearing in real-time.

## API Configuration

### Base URL
```
https://openrouter.ai/api
```

### Authentication
Use your OpenRouter API key as the auth token.

### Provider Priority
**Important**: Claude Code with OpenRouter is only guaranteed to work with the Anthropic first-party provider. For maximum compatibility, we recommend setting **Anthropic 1P** as the top priority provider when using Claude Code.

## Supported Models

When using Claude Code through OpenRouter, you can access Anthropic models including:
- Claude 3.5 Sonnet
- Claude 3 Opus
- Claude 3 Haiku

The specific model used depends on your Claude Code configuration and can be set via OpenRouter's model routing settings.

## How It Works

### Direct Connection
When you set `ANTHROPIC_BASE_URL` to `https://openrouter.ai/api`, Claude Code speaks its native protocol directly to OpenRouter. No local proxy server is required.

### Anthropic Skin
OpenRouter's "Anthropic Skin" behaves exactly like the Anthropic API. It handles model mapping and passes through advanced features like "Thinking" blocks and native tool use.

### Billing
You are billed using your OpenRouter credits. Usage (including reasoning tokens) appears in your OpenRouter dashboard.

## Security
The skill handles your API key securely and stores it in your shell environment with appropriate file permissions.

**Privacy Note**: OpenRouter does not log your source code prompts unless you explicitly opt-in to prompt logging in your account settings. See their [Privacy Policy](https://openrouter.ai/privacy) for details.

## Advanced Features

### Cost Tracking Statusline
You can add a custom statusline to Claude Code that tracks your OpenRouter API costs in real-time. The statusline displays provider, model, cumulative cost, and cache discounts for your session.

Download the statusline scripts from the [openrouter-examples repository](https://github.com/openrouter/openrouter-examples), make them executable, and add the following to your `~/.claude/settings.json`:

```json
{
  "statusLine": {
    "type": "command",
    "command": "/path/to/statusline.sh"
  }
}
```

### GitHub Action Integration
You can use OpenRouter with the official [Claude Code GitHub Action](https://github.com/anthropics/claude-code-action). To adapt for OpenRouter, make two changes to the action step:

1. Pass your OpenRouter API key via `anthropic_api_key` (store it as a GitHub secret named `OPENROUTER_API_KEY`)
2. Set `ANTHROPIC_BASE_URL` environment variable to `https://openrouter.ai/api`

Example:
```yaml
- name: Run Claude Code
  uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.OPENROUTER_API_KEY }}
  env:
    ANTHROPIC_BASE_URL: https://openrouter.ai/api
```

### Agent SDK Integration
The [Anthropic Agent SDK](https://github.com/anthropics/anthropic-sdk-typescript) lets you build AI agents programmatically using Python or TypeScript. Since the Agent SDK uses Claude Code as its runtime, you can connect it to OpenRouter using the same environment variables described above.

## Troubleshooting

### Auth Errors
- Ensure `ANTHROPIC_API_KEY` is set to an empty string (`""`)
- If it is unset (null), Claude Code might fall back to its default behavior and try to authenticate with Anthropic servers

### Context Length Errors
- If you hit context limits, consider breaking your task into smaller chunks or starting a new session

### Previous Anthropic Login
- If you were previously logged in to Claude Code with Anthropic, run `/logout` in a Claude Code session to clear cached credentials before the OpenRouter configuration takes effect

### Connection Issues
- Verify your OpenRouter API key is correct
- Check that environment variables are set in your shell profile (not just in current session)
- Ensure you've restarted your terminal after updating your shell profile
- Run `/status` to verify configuration

## Related Skills
- API Key Management
- Provider Configuration
- Model Selection
- Cost Tracking

## Example Commands
- "Configure OpenRouter with my API key"
- "Set up OpenRouter as my AI provider for Claude Code"
- "Enable OpenRouter in Claude Code"
- "Configure OpenRouter with provider failover"

## Notes
- This skill is designed specifically for Claude Code
- It requires write access to your shell profile (~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish)
- The skill ensures OpenRouter is used exclusively with Anthropic 1P as top priority
- You can revert to using Anthropic directly by removing these environment variables and running `/logout`
- Always refer to the [official OpenRouter documentation](https://openrouter.ai/docs/guides/claude-code-integration) for the most up-to-date information