From 1f1edcf7dd4a53503e306c7023f9361be2b37824 Mon Sep 17 00:00:00 2001 From: Z User Date: Sun, 22 Feb 2026 13:02:18 +0000 Subject: [PATCH] Update OpenRouter Config skill with complete documentation - Add official OpenRouter documentation source link - Include API endpoint (https://openrouter.ai/api) - Add all required environment variables with explanations - Document provider priority (Anthropic 1P) - Add detailed benefits: failover, budget controls, analytics - Include verification steps with /status command - Add troubleshooting section - Document advanced features: statusline, GitHub Action, Agent SDK - Add security and privacy notes - Include important notes about ANTHROPIC_API_KEY being empty - Reference official docs for up-to-date information --- skills/openrouter-config/README.md | 178 +++++++++++++++++++++++---- skills/openrouter-config/SKILL.md | 188 ++++++++++++++++++++++++----- 2 files changed, 316 insertions(+), 50 deletions(-) diff --git a/skills/openrouter-config/README.md b/skills/openrouter-config/README.md index d1bee05..a7af104 100644 --- a/skills/openrouter-config/README.md +++ b/skills/openrouter-config/README.md @@ -1,53 +1,187 @@ # 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 model, and ensures Claude Code uses OpenRouter exclusively. +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 default model (arcee-ai/trinity-mini:free) +2. Configure the Anthropic-compatible environment variables 3. Ensure Claude Code uses OpenRouter exclusively -4. Update the configuration file +4. Set up proper provider priority (Anthropic 1P) +5. Verify the configuration is working ## Prerequisites -- An OpenRouter API key +- An OpenRouter API key (get one from https://openrouter.ai/keys) - Claude Code installed ## Configuration Steps -1. The skill will prompt you for your OpenRouter API key -2. It will update the Claude Code configuration file -3. It will verify the configuration is working -4. It will provide instructions for testing + +### 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="" +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 -The skill configures the following model by default: -- arcee-ai/trinity-mini:free -You can change this to any other OpenRouter model if needed. +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 the Claude Code configuration file with appropriate permissions. +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 -If you encounter issues: -- Check that your API key is correct -- Verify the configuration file has been updated -- Ensure Claude Code has the necessary permissions -- Contact support if problems persist + +### 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" +- "Set up OpenRouter as my AI provider for Claude Code" - "Enable OpenRouter in Claude Code" +- "Configure OpenRouter with provider failover" ## Notes -- This skill only works with Claude Code -- It requires write access to the configuration file -- The skill ensures OpenRouter is used exclusively -- You can revert to other providers by modifying the configuration manually \ No newline at end of file +- 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 \ No newline at end of file diff --git a/skills/openrouter-config/SKILL.md b/skills/openrouter-config/SKILL.md index 7f092f8..8321085 100644 --- a/skills/openrouter-config/SKILL.md +++ b/skills/openrouter-config/SKILL.md @@ -1,27 +1,79 @@ --- name: openrouter-config -description: Use this skill when the user asks to "configure OpenRouter", "set up OpenRouter API key", "enable OpenRouter as AI provider", "configure OpenRouter in Claude Code", "set OpenRouter model", or mentions configuring OpenRouter for Claude Code. +description: Use this skill when the user asks to "configure OpenRouter", "set up OpenRouter API key", "enable OpenRouter as AI provider", "configure OpenRouter in Claude Code", "set OpenRouter model", "connect Claude Code to OpenRouter", or mentions configuring OpenRouter for Claude Code. version: 1.0.0 --- # OpenRouter Config Skill -Helps users configure and enable OpenRouter as the AI provider in Claude Code by setting up the OpenRouter API key, configuring the model, and ensuring Claude Code uses OpenRouter exclusively. +Helps users configure and enable OpenRouter as the AI provider for Claude Code by setting up the OpenRouter API key, configuring Anthropic-compatible environment variables, and ensuring proper provider priority and failover capabilities. + +## Documentation Source +Official OpenRouter Claude Code Integration Guide: https://openrouter.ai/docs/guides/claude-code-integration ## What It Does 1. **API Key Setup**: Securely configures the OpenRouter API key -2. **Model Configuration**: Sets the default OpenRouter model (arcee-ai/trinity-mini:free) -3. **Provider Configuration**: Ensures Claude Code uses OpenRouter exclusively -4. **Configuration Verification**: Validates that the configuration is working correctly +2. **Environment Configuration**: Sets up Anthropic-compatible environment variables +3. **Provider Priority**: Ensures Anthropic 1P is set as top priority provider +4. **API Endpoint Configuration**: Configures `https://openrouter.ai/api` as the base URL +5. **Configuration Verification**: Validates that the configuration is working correctly +6. **Failover Setup**: Enables automatic provider failover for high availability -## Quick Commands +## Key Benefits +### 1. Provider Failover for High Availability +Anthropic's API occasionally experiences outages or rate limiting. OpenRouter automatically fails over between multiple Anthropic providers, keeping coding sessions uninterrupted. + +### 2. Organizational Budget Controls +Centralized budget management with spending limits, credit allocation, and cost overrun prevention for teams. + +### 3. Usage Visibility and Analytics +Complete visibility into Claude Code usage across teams, including usage patterns, real-time cost monitoring, and resource consumption tracking via the [OpenRouter Activity Dashboard](https://openrouter.ai/dashboard/activity). + +## Quick Start + +### Environment Variables to Configure ```bash -# The skill will handle all configuration automatically -# No manual commands needed +export 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 ``` +### Shell Profile Locations +Add to one of these files: +- `~/.bashrc` for Bash +- `~/.zshrc` for Zsh +- `~/.config/fish/config.fish` for Fish + +**Important**: Do NOT add these to a project-level `.env` file - Claude Code's native installer does not read standard `.env` files. + +### Verification +Run `/status` inside Claude Code to verify: +``` +/status +``` + +Expected output: +``` +Auth token: ANTHROPIC_AUTH_TOKEN +Anthropic base URL: https://openrouter.ai/api +``` + +## API Configuration + +### Base URL +``` +https://openrouter.ai/api +``` + +### Authentication +OpenRouter API key (get from https://openrouter.ai/keys) + +### Provider Priority +**Critical**: Set **Anthropic 1P** as top priority provider for maximum compatibility with Claude Code. + ## Usage ``` @@ -29,39 +81,119 @@ Helps users configure and enable OpenRouter as the AI provider in Claude Code by "Set up OpenRouter as my AI provider" "Enable OpenRouter in Claude Code" "Configure OpenRouter for Claude Code" +"Connect Claude Code to OpenRouter" ``` -## Configuration File Location +## How It Works -The skill updates the Claude Code configuration file with: -- OpenRouter API key -- Default model (arcee-ai/trinity-mini:free) -- Provider settings +### Direct Connection +Claude Code speaks its native protocol directly to OpenRouter when `ANTHROPIC_BASE_URL` is set to `https://openrouter.ai/api`. No local proxy server is required. -## Supported Models +### Anthropic Skin +OpenRouter's "Anthropic Skin" behaves exactly like the Anthropic API, handling model mapping and passing through advanced features like "Thinking" blocks and native tool use. -Default: `arcee-ai/trinity-mini:free` +### Billing +Billed using OpenRouter credits. Usage (including reasoning tokens) appears in the OpenRouter dashboard. -You can configure any other OpenRouter model by modifying the configuration. +## Important Notes + +### Previous Anthropic Login +If previously logged in to Claude Code with Anthropic, run `/logout` in a Claude Code session to clear cached credentials before OpenRouter configuration takes effect. + +### Explicit Empty API Key +`ANTHROPIC_API_KEY` must be set to an empty string (`""`), not unset. If unset (null), Claude Code may fall back to default behavior and authenticate with Anthropic servers directly. + +### Shell Profile Persistence +Environment variables should be added to your shell profile for persistence across sessions. + +### Claude Code Models +When using Claude Code through OpenRouter, you access Anthropic models including Claude 3.5 Sonnet, Claude 3 Opus, and Claude 3 Haiku. + +## Advanced Features + +### Cost Tracking Statusline +Download statusline scripts from [openrouter-examples repository](https://github.com/openrouter/openrouter-examples) and add to `~/.claude/settings.json`: + +```json +{ + "statusLine": { + "type": "command", + "command": "/path/to/statusline.sh" + } +} +``` + +### GitHub Action Integration +```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 uses the same environment variables for OpenRouter integration. ## Security Notes -- The skill handles API keys securely -- Stores credentials with appropriate file permissions -- Follows best practices for credential management +- API keys are stored in shell environment with appropriate file permissions +- OpenRouter does not log source code prompts unless you explicitly opt-in to prompt logging +- See [OpenRouter Privacy Policy](https://openrouter.ai/privacy) for details ## Troubleshooting -If you encounter issues: -- Verify your API key is correct -- Check configuration file permissions -- Ensure Claude Code has write access to configuration directory -- Test with a simple query to verify the connection +### Auth Errors +- Ensure `ANTHROPIC_API_KEY` is set to empty string (`""`) +- Check that environment variables are set in shell profile (not just current session) +- Restart terminal after updating shell profile + +### Context Length Errors +- Break tasks into smaller chunks +- Start a new session + +### Connection Issues +- Verify OpenRouter API key is correct +- Check all environment variables are set correctly +- Run `/status` to verify configuration +- Check [OpenRouter Activity Dashboard](https://openrouter.ai/dashboard/activity) for requests appearing + +### Previous Credentials +- Run `/logout` to clear cached Anthropic credentials +- Restart Claude Code after environment variable changes ## Example Workflow 1. User requests: "Configure OpenRouter for Claude Code" -2. Skill prompts for API key -3. Skill updates configuration file -4. Skill verifies configuration -5. User can now use Claude Code with OpenRouter \ No newline at end of file +2. Skill prompts for OpenRouter API key +3. Skill adds environment variables to shell profile +4. Skill reminds user to restart terminal +5. User restarts terminal and runs `claude` +6. User runs `/status` to verify configuration +7. User can now use Claude Code with OpenRouter's failover and analytics + +## Configuration File Location + +Environment variables are added to shell profile: +- `~/.bashrc`, `~/.zshrc`, or `~/.config/fish/config.fish` + +Claude Code settings (optional): +- `~/.claude/settings.json` (for statusline) + +## Supported Models + +Anthropic models accessed through OpenRouter: +- Claude 3.5 Sonnet +- Claude 3 Opus +- Claude 3 Haiku + +Model selection depends on Claude Code configuration and OpenRouter model routing settings. + +## Related Resources + +- [OpenRouter Claude Code Integration Guide](https://openrouter.ai/docs/guides/claude-code-integration) +- [OpenRouter Activity Dashboard](https://openrouter.ai/dashboard/activity) +- [OpenRouter API Keys](https://openrouter.ai/keys) +- [OpenRouter Examples Repository](https://github.com/openrouter/openrouter-examples) +- [Anthropic Agent SDK](https://github.com/anthropics/anthropic-sdk-typescript) \ No newline at end of file