# BitRouter
> BitRouter is an agent-native LLM router that optimizes your agent with every run — a single local binary that gives any agent one endpoint to discover, route to, and pay for 200+ models across OpenAI, Anthropic, Google, and permissionlessly-registered providers, with zero harness changes. Point any runtime at it and every model call becomes reliable, traceable, secure, and cost-effective. Built for autonomous agent loops with cross-protocol routing (OpenAI Chat + Responses, Anthropic Messages, Google Generative AI), runtime guardrails, CLI/TUI observability, and agent-native auth and payment (KYA identity, x402/MPP stablecoins). Self-host the Apache-2.0 binary with your own provider keys at zero cost, or use the hosted node — no KYC, no geo-restrictions.
## Key Facts
- Four mechanisms built into the router: Reliability (transparent multi-provider failover mid-run, so one outage doesn't kill an agent run), Observability (full call-chain traces with cost attributed per run), Security (prompt-injection detection, PII/output redaction, and rate limits enforced once at the router), Efficiency (price-aware model-per-task routing — match each call to the right model by complexity).
- Zero harness changes: drop-in proxy for any runtime with a custom OpenAI or Anthropic base URL. Local proxy at http://localhost:8787; hosted API at https://api.bitrouter.ai/v1.
- Zero-ops: single Rust binary, no Postgres/Redis/Docker, ~5ms p50 routing overhead.
- Free BYOK auto-detected from environment variables; failed requests are never billed.
- Pricing: 2% on usage with USDC/USDT over x402/MPP, 5% with card (Stripe fees absorbed). No token markup, no minimums, no monthly fee. Self-host has no platform fee at all.
- Apache 2.0, open-sourced; Cloud is opt-in.
## How BitRouter Compares
BitRouter, LiteLLM, and OpenRouter all route LLM traffic — BitRouter is the open, agent-native one.
- Open source & self-hostable: BitRouter — Apache 2.0 single binary; LiteLLM — partial (Python + Postgres + Redis); OpenRouter — closed.
- Permissionless provider marketplace: BitRouter — yes, PR-based; LiteLLM — no; OpenRouter — curated only.
- Agent gateway (MCP / ACP / Skills + KYA + guardrails): BitRouter — built-in; LiteLLM — no; OpenRouter — no.
- Autonomous agent payments (x402 / MPP): BitRouter — yes; LiteLLM — no; OpenRouter — no.
- Multi-provider failover mid-run: BitRouter — automatic; LiteLLM — manual; OpenRouter — limited.
- Routing overhead: BitRouter — ~5ms p50; LiteLLM — higher (Python GIL); OpenRouter — ~30ms.
# Cookbook (/docs/cookbook)
Browse [Integration](/docs/cookbook/integration/claude-code) to connect AI coding agents to BitRouter, or [Migration](/docs/cookbook/migration/litellm) to move from LiteLLM or OpenRouter.
# API Reference (/docs/api-reference)
import { Callout } from 'fumadocs-ui/components/callout';
The BitRouter API is in **early beta**. Endpoints, request/response formats, and behavior may change without notice.
Base URL: `https://api.bitrouter.ai`. Most endpoints live under `/v1`. Routing endpoints accept either `x-api-key: ` or `Authorization: Bearer `. Pick an endpoint group from the sidebar.
# Docs (/docs/guides)
Start with the [Overview](/docs/guides/overview) for a quick tour. From there, dive into [Models & Routing](/docs/guides/routing/model-fallback) or [Features](/docs/guides/features/workspaces).
# Claude Code (/docs/cookbook/integration/claude-code)
Claude Code Integration [#claude-code-integration]
Quick Start [#quick-start]
```bash
# 1. Start BitRouter
bitrouter serve
# 2. Configure Claude Code
export ANTHROPIC_API_BASE=http://localhost:8787
# 3. Launch Claude Code
claude
```
What You Get [#what-you-get]
* ✅ **Multi-provider access** - Route to OpenAI, Google, DeepSeek beyond Anthropic
* ✅ **Cost optimization** - Automatically use cheaper models for simple tasks
* ✅ **Fallback providers** - Never get blocked by API outages
* ✅ **Session tracking** - Monitor all Claude Code sessions in one place
* ✅ **MCP gateway** - Access all MCP tools through BitRouter
Installation [#installation]
Prerequisites [#prerequisites]
```bash
# Install Claude Code (choose one)
winget install Anthropic.ClaudeCode # Windows
code --install-extension claude-code # VS Code
```
Connect to BitRouter [#connect-to-bitrouter]
Choose your integration method:
Option 1: Simple API Proxy [#option-1-simple-api-proxy]
```bash
export ANTHROPIC_API_BASE=http://localhost:8787
claude
```
Option 2: ACP Protocol (Advanced) [#option-2-acp-protocol-advanced]
```bash
# Terminal 1: Start BitRouter with ACP
bitrouter acp
# Terminal 2: Connect Claude Code
claude --api-base http://localhost:8787 --protocol acp
```
Option 3: Skills Integration [#option-3-skills-integration]
```bash
# Auto-configure with skills
npx skills add BitRouterAI/claude-code-integration
claude
```
Essential Configuration [#essential-configuration]
Smart Task Routing [#smart-task-routing]
```yaml
# ~/.bitrouter/config.yaml
routes:
# Heavy refactoring → Most capable model
- match: "claude-code/refactor/*"
provider: anthropic
model: claude-3-5-sonnet-latest
# Test generation → Specialized model
- match: "claude-code/test/*"
provider: deepseek
model: deepseek-coder
# Quick fixes → Fast & cheap model
- match: "claude-code/quick/*"
provider: openai
model: gpt-4o-mini
# Documentation → Optimized model
- match: "claude-code/docs/*"
provider: anthropic
model: claude-3-5-haiku-latest
```
High Availability Setup [#high-availability-setup]
```yaml
routes:
- match: "claude-code/*"
provider: anthropic
model: claude-3-5-sonnet-latest
fallback:
- provider: openai
model: gpt-4o
- provider: google
model: gemini-2.0-flash-exp
```
Budget Controls [#budget-controls]
```yaml
budget:
claude-code:
limits:
hourly: 5.00
daily: 50.00
alerts:
- at: 80%
action: notify
- at: 100%
action: block
```
Common Recipes [#common-recipes]
Recipe: Cost-Optimized Development [#recipe-cost-optimized-development]
```yaml
# Route by task complexity
routes:
- match: "claude-code/*"
rules:
- if: complexity == "simple"
model: gpt-4o-mini
- if: complexity == "moderate"
model: claude-3-5-haiku-latest
- if: complexity == "complex"
model: claude-3-5-sonnet-latest
```
Recipe: Team Collaboration [#recipe-team-collaboration]
```bash
# Export team config
bitrouter config export > team-config.yaml
# Team members import
bitrouter config import team-config.yaml
```
Recipe: MCP Tools Access [#recipe-mcp-tools-access]
```yaml
mcp_servers:
- name: github
command: npx @modelcontextprotocol/server-github
- name: filesystem
command: npx @modelcontextprotocol/server-filesystem
args: ["--root", "/code"]
routes:
- match: "claude-code/*"
mcp_access: [github, filesystem]
```
CLAUDE.md Configuration [#claudemd-configuration]
Enhance Claude Code's behavior with a project-specific config:
```markdown
# Project Configuration
## BitRouter Settings
- Use `claude-code/test/*` route for test generation
- Use `claude-code/docs/*` route for documentation
- Use `claude-code/refactor/*` route for major refactoring
## Coding Standards
- Follow existing code style
- Write comprehensive tests
- Document complex logic
```
Monitoring [#monitoring]
Real-time Session Tracking [#real-time-session-tracking]
```bash
# View active sessions
bitrouter sessions list --agent claude-code
# Monitor live session
bitrouter monitor --agent claude-code --live
# Export session data
bitrouter sessions export --format json
```
Cost Analytics [#cost-analytics]
```bash
# Current spending
bitrouter costs show --agent claude-code
# Daily breakdown
bitrouter costs breakdown --agent claude-code --by day
# Set spending alert
bitrouter budget alert --agent claude-code --at 80%
```
Troubleshooting [#troubleshooting]
🔴 Connection Issues [#-connection-issues]
```bash
# Verify BitRouter is running
curl http://localhost:8787/health
# Check Claude Code config
claude config show
# Test with debug mode
RUST_LOG=debug bitrouter serve
claude --verbose
```
🟡 Performance Problems [#-performance-problems]
```bash
# Benchmark providers
bitrouter providers benchmark
# Enable caching
bitrouter config set cache.enabled true
# Optimize routing
bitrouter routes optimize --agent claude-code
```
🔵 Authentication Errors [#-authentication-errors]
```bash
# Validate all API keys
bitrouter config validate
# Test specific provider
bitrouter providers test anthropic
# Re-authenticate
claude auth refresh
```
Advanced Features [#advanced-features]
Context Window Management [#context-window-management]
```yaml
routes:
- match: "claude-code/*"
options:
max_tokens: 8192
compress_context: true
cache_enabled: true
```
Custom Hooks [#custom-hooks]
```yaml
hooks:
pre_request:
- name: security_scan
command: ./scan_request.sh
post_response:
- name: log_activity
command: ./log_activity.sh
```
Learn More [#learn-more]
* 📚 [Claude Code Documentation](https://docs.anthropic.com/claude-code)
* 🎯 [BitRouter Skills](https://github.com/bitrouter/claude-code-skills)
* 💡 [Example Configs](https://github.com/bitrouter/examples/claude-code)
* 💬 [Discord Community](https://discord.gg/G3zVrZDa5C)
# Codex (/docs/cookbook/integration/codex)
Codex Integration [#codex-integration]
Quick Start [#quick-start]
```bash
# 1. Start BitRouter
bitrouter serve
# 2. Configure Codex CLI
codex config set api.base http://localhost:8787
# 3. Launch Codex
codex init
```
What You Get [#what-you-get]
* ✅ **Multi-provider routing** - Beyond OpenAI models to Anthropic, Google, etc.
* ✅ **Local control** - Manage cloud operations from your proxy
* ✅ **Cost tracking** - Monitor parallel execution spending
* ✅ **Fallback providers** - Never blocked by OpenAI limits
* ✅ **Enhanced security** - Guardrails at the proxy layer
Installation [#installation]
Prerequisites [#prerequisites]
```bash
# Install Codex CLI
npm i -g @openai/codex
# Or use desktop app
# Download from chatgpt.com/codex
```
Connect to BitRouter [#connect-to-bitrouter]
Choose your setup:
Option 1: CLI Configuration [#option-1-cli-configuration]
```bash
codex config set api.base http://localhost:8787
codex config set api.protocol openai
codex init
```
Option 2: Desktop App [#option-2-desktop-app]
```bash
export OPENAI_API_BASE=http://localhost:8787
codex-app
```
Option 3: Browser Extension [#option-3-browser-extension]
```javascript
// In browser console
localStorage.setItem('codex_api_base', 'http://localhost:8787');
```
Essential Configuration [#essential-configuration]
Smart Routing by Task [#smart-routing-by-task]
```yaml
# ~/.bitrouter/config.yaml
routes:
# Main Codex operations
- match: "codex/main/*"
provider: openai
model: codex-1
# Code review & analysis
- match: "codex/review/*"
provider: anthropic
model: claude-3-5-sonnet-latest
# Test generation
- match: "codex/test/*"
provider: deepseek
model: deepseek-coder
# Documentation
- match: "codex/docs/*"
provider: google
model: gemini-2.0-flash-exp
```
Parallel Execution Support [#parallel-execution-support]
```yaml
routes:
- match: "codex/parallel/*"
provider: openai
model: codex-1
options:
max_parallel: 5
timeout: 300s
load_balancing:
strategy: round_robin
```
Automation Workflows [#automation-workflows]
```yaml
automations:
issue_triage:
route: "codex/automation/triage"
provider: openai
model: gpt-4o
schedule: "*/15 * * * *"
ci_monitoring:
route: "codex/automation/ci"
provider: anthropic
model: claude-3-5-haiku-latest
trigger: webhook
```
Common Recipes [#common-recipes]
Recipe: High Availability [#recipe-high-availability]
```yaml
routes:
- match: "codex/*"
provider: openai
model: codex-1
fallback:
- provider: anthropic
model: claude-3-5-sonnet-latest
- provider: google
model: gemini-2.0-flash-exp
```
Recipe: Cost Optimization [#recipe-cost-optimization]
```yaml
cloud_resources:
cost_limits:
hourly: 50.00
daily: 500.00
auto_scale:
enabled: true
min_instances: 2
max_instances: 20
```
Recipe: Skills Integration [#recipe-skills-integration]
```yaml
skills:
routing:
- skill: "code-understanding"
provider: openai
model: codex-1
- skill: "prototyping"
provider: anthropic
model: claude-3-5-sonnet-latest
```
Monitoring [#monitoring]
Session Tracking [#session-tracking]
```bash
# List Codex sessions
bitrouter sessions list --agent codex
# View parallel execution
bitrouter codex status --show-parallel
# Export metrics
bitrouter sessions export --agent codex --format csv
```
Cost Analytics [#cost-analytics]
```bash
# Spending breakdown
bitrouter costs breakdown --agent codex
# Set budget alert
bitrouter budget set --agent codex --daily 100
# Generate report
bitrouter report generate --agent codex --period month
```
Troubleshooting [#troubleshooting]
🔴 Connection Failed [#-connection-failed]
```bash
# Check BitRouter
curl http://localhost:8787/health
# Verify Codex config
codex config list
# Reset API base
codex config set api.base http://localhost:8787
```
🟡 Cloud Environment Issues [#-cloud-environment-issues]
```bash
# Test connectivity
bitrouter providers test openai
# Check credentials
codex auth status
# Restart Codex
codex restart
```
🔵 Performance Problems [#-performance-problems]
```bash
# Analyze routing
bitrouter performance analyze --agent codex
# Optimize routes
bitrouter routes optimize --agent codex
# Clear cache
bitrouter cache clear --agent codex
```
Advanced Features [#advanced-features]
Environment Routing [#environment-routing]
```yaml
environments:
development:
route: "codex/dev/*"
provider: openai
model: gpt-4o
production:
route: "codex/prod/*"
provider: openai
model: codex-1
guardrails:
- approval_required
- audit_log
```
Security Guardrails [#security-guardrails]
```yaml
guardrails:
codex:
- type: secret_detection
action: redact
- type: pii_protection
action: block
- type: code_security
scan_for: [sql_injection, xss]
```
Learn More [#learn-more]
* 📚 [Codex Documentation](https://platform.openai.com/docs/guides/codex)
* 🔧 [BitRouter Codex Skills](https://github.com/bitrouter/codex-skills)
* 💡 [Cloud Integration Examples](https://github.com/bitrouter/examples/codex)
* 💬 [Discord Community](https://discord.gg/G3zVrZDa5C)
# GitHub Copilot (/docs/cookbook/integration/github-copilot)
GitHub Copilot Integration [#github-copilot-integration]
Quick Start [#quick-start]
```bash
# 1. Start BitRouter
bitrouter serve
# 2. Add to VS Code settings.json
# "github.copilot.advanced": {
# "debug.overrideProxyUrl": "http://localhost:8787"
# }
# 3. Reload VS Code — Copilot now routes through BitRouter
```
What You Get [#what-you-get]
* ✅ **25+ LLM providers** - Route Copilot requests through any BitRouter provider
* ✅ **VS Code + CLI** - Both the extension and `gh copilot` CLI are supported
* ✅ **Cost tracking** - Monitor spending across all Copilot sessions
* ✅ **BYOK support** - Bring your own API keys for Business/Enterprise plans
* ✅ **Fallback routing** - Automatic failover when a provider is unavailable
Installation [#installation]
Prerequisites [#prerequisites]
```bash
# VS Code extension — search "GitHub Copilot" in Extensions panel
# or install via CLI:
code --install-extension GitHub.copilot
# GitHub Copilot CLI (optional)
gh extension install github/gh-copilot
```
Connect to BitRouter [#connect-to-bitrouter]
Choose your approach based on your VS Code version and Copilot plan:
Option 1: Debug Proxy Override (Stable VS Code, any plan) [#option-1-debug-proxy-override-stable-vs-code-any-plan]
```json
// .vscode/settings.json or user settings
{
"github.copilot.advanced": {
"debug.overrideProxyUrl": "http://localhost:8787",
"debug.testOverrideProxyUrl": "http://localhost:8787"
}
}
```
Reload VS Code after saving. This routes all Copilot completions and chat through BitRouter.
Option 2: BYOK Custom Endpoint (VS Code Insiders, Business/Enterprise) [#option-2-byok-custom-endpoint-vs-code-insiders-businessenterprise]
```json
// chatLanguageModels.json (Command Palette: "Chat: Manage Language Models")
[
{
"name": "BitRouter",
"vendor": "customendpoint",
"apiKey": "your-bitrouter-key",
"apiType": "chat-completions",
"models": [
{
"id": "claude-3-5-sonnet-latest",
"name": "BitRouter → Claude 3.5 Sonnet",
"url": "http://localhost:8787/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 200000,
"maxOutputTokens": 8192
},
{
"id": "gpt-4o",
"name": "BitRouter → GPT-4o",
"url": "http://localhost:8787/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 128000,
"maxOutputTokens": 4096
}
]
}
]
```
Option 3: Copilot CLI (gh copilot) [#option-3-copilot-cli-gh-copilot]
```bash
export COPILOT_PROVIDER_BASE_URL="http://localhost:8787/v1"
export COPILOT_MODEL="claude-3-5-sonnet-latest"
export COPILOT_PROVIDER_API_KEY="your-bitrouter-key"
export COPILOT_OFFLINE="true" # prevent silent fallback to GitHub-hosted models
gh copilot suggest "create a docker-compose for a postgres + redis stack"
gh copilot explain "$(cat main.go)"
```
Essential Configuration [#essential-configuration]
Multi-Provider Routing [#multi-provider-routing]
```yaml
# ~/.bitrouter/config.yaml
routes:
# Copilot completions — fast, cheap model
- match: "copilot/completions/*"
provider: openai
model: gpt-4o-mini
# Copilot Chat — more capable model
- match: "copilot/chat/*"
provider: anthropic
model: claude-3-5-sonnet-latest
# Complex refactoring tasks
- match: "copilot/chat/refactor/*"
provider: openai
model: o1-preview
# Local models via Ollama
- match: "copilot/local/*"
provider: ollama
model: codellama:34b
endpoint: http://localhost:11434
```
HTTP Proxy (Network-Level) [#http-proxy-network-level]
For corporate environments that need all traffic routed through a proxy:
```json
{
"http.proxy": "http://localhost:8787",
"http.proxySupport": "on",
"http.proxyStrictSSL": false
}
```
```bash
# Or via environment variables
export HTTPS_PROXY=http://localhost:8787
export HTTP_PROXY=http://localhost:8787
```
Cost Budgets [#cost-budgets]
```yaml
budgets:
copilot:
daily: 10.00
per_session: 2.00
alert_threshold: 0.80 # alert at 80% of budget
```
Common Recipes [#common-recipes]
Recipe: Inline Completions vs Chat Routing [#recipe-inline-completions-vs-chat-routing]
```yaml
routes:
# Fast, low-latency for inline completions
- match: "copilot/completions/*"
provider: openai
model: gpt-4o-mini
max_latency_ms: 800
# Full-context chat with Claude
- match: "copilot/chat/*"
provider: anthropic
model: claude-3-5-sonnet-latest
```
Recipe: Fallback Chain [#recipe-fallback-chain]
```yaml
routes:
- match: "copilot/*"
provider: anthropic
model: claude-3-5-sonnet-latest
fallback:
- provider: openai
model: gpt-4o
- provider: deepseek
model: deepseek-coder
```
Recipe: Cost-Optimized Setup [#recipe-cost-optimized-setup]
```yaml
routes:
- match: "copilot/*"
rules:
- if: context_tokens < 4000
provider: openai
model: gpt-4o-mini
- if: context_tokens >= 4000
provider: deepseek
model: deepseek-coder
```
Monitoring [#monitoring]
Usage Dashboard [#usage-dashboard]
```bash
# Copilot session summary
bitrouter sessions list --agent copilot
# Token usage by model
bitrouter usage breakdown --agent copilot --group-by model
# Daily spend
bitrouter costs breakdown --agent copilot --period day
```
Latency Tracking [#latency-tracking]
```bash
# P95 latency per route
bitrouter stats latency --agent copilot
# Provider comparison
bitrouter providers benchmark --agent copilot
```
Troubleshooting [#troubleshooting]
🔴 Copilot Not Using BitRouter [#-copilot-not-using-bitrouter]
```bash
# Verify BitRouter is running
curl http://localhost:8787/health
# Check VS Code setting is saved
code --list-extensions | grep copilot
# Open settings.json, confirm debug.overrideProxyUrl is set
# Reload VS Code window
# Command Palette: "Developer: Reload Window"
```
🟡 BYOK Endpoint Not Appearing in Chat [#-byok-endpoint-not-appearing-in-chat]
```bash
# Confirm you're on VS Code Insiders with a Business/Enterprise plan
# Open Command Palette: "Chat: Manage Language Models"
# Re-enter the chatLanguageModels.json configuration
# Test the endpoint directly
curl http://localhost:8787/v1/models
```
🔵 Copilot CLI Falling Back to Cloud [#-copilot-cli-falling-back-to-cloud]
```bash
# Ensure COPILOT_OFFLINE=true is set
echo $COPILOT_OFFLINE
# Verify base URL includes /v1
echo $COPILOT_PROVIDER_BASE_URL # should end with /v1
# Test the endpoint
curl http://localhost:8787/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"gpt-4o","messages":[{"role":"user","content":"hello"}]}'
```
Advanced Features [#advanced-features]
Workspace-Scoped Routing [#workspace-scoped-routing]
```json
// .vscode/settings.json (project-level, overrides user settings)
{
"github.copilot.advanced": {
"debug.overrideProxyUrl": "http://localhost:8787"
}
}
```
Commit this to your repo so every team member routes through the shared BitRouter instance.
Enterprise Proxy with Auth [#enterprise-proxy-with-auth]
```yaml
# ~/.bitrouter/config.yaml
providers:
copilot_enterprise:
type: github_copilot
enterprise_url: https://github.yourcompany.com
auth: bearer
route_prefix: "copilot/enterprise/*"
```
Model Overrides by File Type [#model-overrides-by-file-type]
```yaml
routes:
- match: "copilot/*"
rules:
- if: file_extension in [".py", ".ipynb"]
model: deepseek-coder-v2
- if: file_extension in [".rs", ".go"]
model: claude-3-5-sonnet-latest
- default:
model: gpt-4o-mini
```
Learn More [#learn-more]
* 📚 [GitHub Copilot Docs](https://docs.github.com/en/copilot)
* 🔧 [Copilot Network Settings](https://docs.github.com/en/copilot/managing-copilot/configure-personal-settings/configuring-network-settings-for-github-copilot)
* 🔑 [BYOK / Custom Endpoints](https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-enterprise/use-your-own-api-keys)
* 🖥️ [Copilot CLI BYOK](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/use-byok-models)
* 💬 [Discord Community](https://discord.gg/G3zVrZDa5C)
# Hermes (/docs/cookbook/integration/hermes)
Hermes Integration [#hermes-integration]
Quick Start [#quick-start]
```bash
# 1. Start BitRouter with memory support
bitrouter acp --enable-memory
# 2. Configure Hermes
hermes config set backend bitrouter
hermes config set bitrouter.url http://localhost:8787
# 3. Launch with persistent memory
hermes start --memory persistent
```
What You Get [#what-you-get]
* ✅ **Persistent memory** - Learning that survives restarts
* ✅ **Multi-provider learning** - Diverse model experiences
* ✅ **Cost-optimized sessions** - Smart routing for long runs
* ✅ **Learning trajectories** - Track improvement over time
* ✅ **Research-ready** - Batch processing and exports
Installation [#installation]
Prerequisites [#prerequisites]
```bash
# Install Hermes
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
# Verify 64k+ context models available
bitrouter models list --min-context 64000
```
Connect to BitRouter [#connect-to-bitrouter]
Choose your backend:
Option 1: ACP Integration (Recommended) [#option-1-acp-integration-recommended]
```bash
hermes config set backend bitrouter
hermes config set protocol acp
hermes config set bitrouter.url http://localhost:8787
hermes start --memory persistent
```
Option 2: Direct API [#option-2-direct-api]
```bash
export HERMES_API_BASE=http://localhost:8787
hermes start --provider custom
```
Option 3: Multi-Backend [#option-3-multi-backend]
```bash
hermes config set backends.primary bitrouter
hermes config set backends.primary.url http://localhost:8787
hermes start --multi-backend
```
Essential Configuration [#essential-configuration]
Memory-Optimized Routing [#memory-optimized-routing]
```yaml
# ~/.bitrouter/config.yaml
routes:
# Learning operations - large context
- match: "hermes/learn/*"
provider: anthropic
model: claude-3-5-sonnet-latest
options:
max_tokens: 200000
# Memory recall - fast access
- match: "hermes/recall/*"
provider: openai
model: gpt-4o
cache:
enabled: true
ttl: 3600
# Self-improvement cycles
- match: "hermes/improve/*"
provider: anthropic
model: claude-3-5-sonnet-latest
options:
temperature: 0.9
```
Persistent Memory Setup [#persistent-memory-setup]
```yaml
memory:
hermes:
type: persistent
backend: bitrouter
storage:
path: ~/.hermes/memory
encryption: true
sync:
enabled: true
interval: 300s
namespaces:
- name: general
max_size: 10MB
- name: code
max_size: 50MB
```
Learning Cycles [#learning-cycles]
```yaml
learning:
cycles:
- name: "daily_review"
schedule: "0 0 * * *"
route: "hermes/learn/review"
model: claude-3-5-sonnet-latest
- name: "skill_improvement"
trigger: performance_threshold
route: "hermes/learn/skills"
```
Common Recipes [#common-recipes]
Recipe: Research Mode [#recipe-research-mode]
```yaml
research:
enabled: true
trajectory_export: true
batch_processing: true
routing:
control: "hermes/research/control"
treatment: "hermes/research/treatment"
```
Recipe: Multi-Platform Memory [#recipe-multi-platform-memory]
```yaml
platforms:
telegram:
route: "hermes/telegram/*"
memory_namespace: "telegram"
discord:
route: "hermes/discord/*"
memory_namespace: "discord"
```
Recipe: Context Optimization [#recipe-context-optimization]
```yaml
context:
hermes:
strategy: sliding_window
window_sizes:
small: 8192
medium: 32768
large: 128000
auto_adjust: true
```
Backend Options [#backend-options]
Local Backend [#local-backend]
```bash
# Docker backend
hermes backend start --type docker \
--routing http://localhost:8787
```
SSH Backend [#ssh-backend]
```bash
# Remote compute
hermes backend start --type ssh \
--host compute.example.com \
--tunnel 8787:8787
```
Cloud Backends [#cloud-backends]
```bash
# Modal backend
hermes backend start --type modal \
--app hermes-agent
# Singularity backend
hermes backend start --type singularity \
--image hermes.sif
```
Monitoring [#monitoring]
Memory Analytics [#memory-analytics]
```bash
# Memory usage
bitrouter memory stats --agent hermes
# Memory patterns
bitrouter memory analyze --agent hermes --period week
# Export snapshot
bitrouter memory export --agent hermes --format json
```
Learning Progress [#learning-progress]
```bash
# Track metrics
bitrouter learning progress --agent hermes
# View improvement
bitrouter learning chart --agent hermes --metric accuracy
# Export data
bitrouter learning export --agent hermes --format csv
```
Troubleshooting [#troubleshooting]
🔴 Memory Not Persisting [#-memory-not-persisting]
```bash
# Check memory backend
hermes memory status
# Verify BitRouter support
bitrouter features list | grep memory
# Test memory ops
hermes memory test --verbose
```
🟡 Context Window Errors [#-context-window-errors]
```bash
# Check model capabilities
bitrouter models list --min-context 64000
# Adjust context
hermes config set max_context 128000
# Enable compression
bitrouter config set compression.enabled true
```
🔵 Learning Loop Failures [#-learning-loop-failures]
```bash
# Check learning status
hermes learning status
# View error logs
bitrouter logs --filter "hermes/learn"
# Reset learning state
hermes learning reset --confirm
```
Advanced Features [#advanced-features]
Multi-Model Ensemble [#multi-model-ensemble]
```yaml
ensemble:
hermes:
models:
- provider: anthropic
model: claude-3-5-sonnet-latest
weight: 0.4
- provider: openai
model: gpt-4o
weight: 0.3
- provider: google
model: gemini-1.5-pro
weight: 0.3
```
Skills Integration [#skills-integration]
```yaml
skills:
source: agentskills.io
routing:
- skill: "code-generation"
route: "hermes/skills/code"
model: deepseek-coder
- skill: "research"
route: "hermes/skills/research"
model: gpt-4o
```
Learn More [#learn-more]
* 📚 [Hermes Documentation](https://github.com/NousResearch/hermes-agent)
* 🧠 [Memory Guide](https://bitrouter.ai/docs/memory)
* 🔬 [Research Examples](https://github.com/bitrouter/examples/hermes)
* 💬 [Discord Community](https://discord.gg/G3zVrZDa5C)
# Agent Integrations (/docs/cookbook/integration)
Agent Integrations [#agent-integrations]
Connect your favorite AI agents to BitRouter's intelligent routing layer.
Quick Integration Matrix [#quick-integration-matrix]
| Agent | Type | Best For | Setup Time |
| --------------------------------------------------------------- | -------------- | ---------------------- | ---------- |
| [**Claude Code**](/docs/cookbook/integration/claude-code) | IDE + CLI | Enterprise development | 2 min |
| [**GitHub Copilot**](/docs/cookbook/integration/github-copilot) | VS Code + CLI | Proxy & BYOK routing | 2 min |
| [**Openclaw**](/docs/cookbook/integration/openclaw) | Multi-channel | Chat platform bots | 5 min |
| [**Pi**](/docs/cookbook/integration/pi) | Terminal | Minimal, extensible | 3 min |
| [**Opencode**](/docs/cookbook/integration/opencode) | Terminal + IDE | Provider-agnostic | 3 min |
| [**Codex**](/docs/cookbook/integration/codex) | Cloud | Parallel execution | 3 min |
| [**KiloCode**](/docs/cookbook/integration/kilocode) | Multi-agent | Role-based teams | 5 min |
| [**Hermes**](/docs/cookbook/integration/hermes) | Research | Persistent memory | 5 min |
Universal Quick Start [#universal-quick-start]
Works with most agents:
```bash
# 1. Start BitRouter
bitrouter serve
# 2. Set API endpoint
export AGENT_API_BASE=http://localhost:8787
# 3. Launch your agent
your-agent-command
```
Integration Methods [#integration-methods]
Method 1: API Proxy (Simple) [#method-1-api-proxy-simple]
Point your agent to BitRouter's OpenAI-compatible endpoint.
Method 2: ACP Protocol (Advanced) [#method-2-acp-protocol-advanced]
Use Agent Communication Protocol for discovery and coordination.
Method 3: Native Plugin [#method-3-native-plugin]
Install BitRouter plugin directly in your agent runtime.
Not Listed? [#not-listed]
Most agents that support custom OpenAI or Anthropic base URLs work with BitRouter out of the box. Check our [universal integration guide](/docs/guides/overview/quickstart) for generic setup instructions.
# KiloCode (/docs/cookbook/integration/kilocode)
KiloCode Integration [#kilocode-integration]
Quick Start [#quick-start]
```bash
# 1. Start BitRouter
bitrouter serve
# 2. Configure KiloCode CLI
kilocode config set api.base http://localhost:8787
# 3. Launch KiloCode
kilocode start --router bitrouter
```
What You Get [#what-you-get]
* ✅ **Multi-agent routing** - Route Architect, Coder, Debugger, Analyst separately
* ✅ **Budget dashboard** - Enhanced expense tracking with BitRouter
* ✅ **500+ model support** - All through BitRouter's unified interface
* ✅ **Smart loop breaking** - Prevent infinite loops across providers
* ✅ **Role-based optimization** - Optimal models per agent specialization
Installation [#installation]
Prerequisites [#prerequisites]
```bash
# Install KiloCode (choose one)
code --install-extension kilocode # VS Code
npm install -g @kilocode/cli # CLI
# Download desktop app from kilocode.ai
```
Connect to BitRouter [#connect-to-bitrouter]
Choose your setup:
Option 1: VS Code Extension [#option-1-vs-code-extension]
```json
// .vscode/settings.json
{
"kilocode.apiBase": "http://localhost:8787",
"kilocode.routing": "bitrouter"
}
```
Option 2: CLI Configuration [#option-2-cli-configuration]
```bash
kilocode config set api.base http://localhost:8787
kilocode config set routing.enabled true
kilocode start --router bitrouter
```
Option 3: Desktop App [#option-3-desktop-app]
```bash
export KILOCODE_API_BASE=http://localhost:8787
kilocode-app
```
Essential Configuration [#essential-configuration]
Role-Based Agent Routing [#role-based-agent-routing]
```yaml
# ~/.bitrouter/config.yaml
routes:
# Architect - planning & design
- match: "kilocode/architect/*"
provider: anthropic
model: claude-3-5-sonnet-latest
options:
temperature: 0.3
# Coder - implementation
- match: "kilocode/coder/*"
provider: openai
model: gpt-4o
options:
temperature: 0.2
# Debugger - fixing issues
- match: "kilocode/debugger/*"
provider: deepseek
model: deepseek-coder
options:
temperature: 0.1
# Analyst - analysis & questions
- match: "kilocode/analyst/*"
provider: google
model: gemini-2.0-flash-exp
options:
temperature: 0.5
```
Budget Management [#budget-management]
```yaml
budget:
kilocode:
limits:
hourly: 10.00
daily: 100.00
monthly: 2000.00
per_agent_limits:
architect: 30.00/day
coder: 40.00/day
debugger: 20.00/day
analyst: 10.00/day
alerts:
- threshold: 80%
action: notify
- threshold: 100%
action: block
```
Loop Breaking & Safety [#loop-breaking--safety]
```yaml
loop_breaker:
kilocode:
enabled: true
detection:
max_iterations: 10
similarity_threshold: 0.9
time_limit: 300s
actions:
- detect: infinite_loop
action: terminate
- detect: repetitive_output
action: switch_model
- detect: cost_spiral
action: pause
```
Common Recipes [#common-recipes]
Recipe: Development Phase Modes [#recipe-development-phase-modes]
```yaml
modes:
kilocode:
planning:
primary_agent: architect
route: "kilocode/mode/planning/*"
model: claude-3-5-sonnet-latest
implementation:
primary_agent: coder
route: "kilocode/mode/coding/*"
model: gpt-4o
debugging:
primary_agent: debugger
route: "kilocode/mode/debug/*"
model: deepseek-coder
```
Recipe: Cost Dashboard [#recipe-cost-dashboard]
```yaml
dashboard:
kilocode:
metrics:
- total_cost
- cost_per_agent
- cost_per_model
- tokens_used
export:
format: csv
schedule: daily
```
Recipe: Multi-IDE Support [#recipe-multi-ide-support]
```yaml
ide_support:
vscode:
route_prefix: "kilocode/vscode"
features: [inline_completions, sidebar_chat, diff_view]
jetbrains:
route_prefix: "kilocode/jetbrains"
features: [code_inspections, refactoring, quick_fixes]
windsurf:
route_prefix: "kilocode/windsurf"
features: [cascade_mode, parallel_edits]
```
Browser Automation [#browser-automation]
Web Development Support [#web-development-support]
```yaml
browser:
kilocode:
enabled: true
automation:
route: "kilocode/browser/*"
provider: openai
model: gpt-4o-vision
capabilities:
- dom_manipulation
- form_filling
- screenshot_analysis
safety:
sandbox_mode: true
max_actions_per_session: 50
```
Monitoring [#monitoring]
Agent Performance [#agent-performance]
```bash
# Monitor agents
bitrouter agents monitor --name kilocode
# Per-agent stats
bitrouter agents stats --breakdown-by-role
# Export performance
bitrouter agents export --name kilocode --format json
```
Budget Analytics [#budget-analytics]
```bash
# Current spending
kilocode budget status
# Spending breakdown
bitrouter costs breakdown --agent kilocode --group-by role
# Set alerts
bitrouter budget alert --agent kilocode --threshold 80%
```
Troubleshooting [#troubleshooting]
🔴 Agent Not Responding [#-agent-not-responding]
```bash
# Check agent status
kilocode agents status
# Verify BitRouter
curl http://localhost:8787/health
# Restart specific agent
kilocode agent restart --name architect
```
🟡 Budget Exceeded [#-budget-exceeded]
```bash
# Check usage
kilocode budget usage
# Adjust limits
bitrouter budget set --agent kilocode --daily 150
# Reset counter
kilocode budget reset --confirm
```
🔵 Loop Detection Triggering [#-loop-detection-triggering]
```bash
# View logs
bitrouter logs --filter "loop_detection"
# Adjust sensitivity
kilocode config set loop_detection.sensitivity medium
# Disable for debugging
kilocode config set loop_detection.enabled false
```
Advanced Features [#advanced-features]
Custom Agent Roles [#custom-agent-roles]
```yaml
custom_agents:
kilocode:
- name: "security-auditor"
route: "kilocode/custom/security/*"
model: claude-3-5-sonnet-latest
capabilities: [vulnerability_scanning, code_audit]
- name: "performance-optimizer"
route: "kilocode/custom/performance/*"
model: gpt-4o
capabilities: [profiling, optimization]
```
File Protection [#file-protection]
```yaml
security:
kilocode:
file_freezing:
enabled: true
protected_patterns:
- "*.env"
- "**/secrets/*"
- "**/config/production/*"
freeze_on:
- production_branch
- sensitive_files
```
Learn More [#learn-more]
* 📚 [KiloCode Documentation](https://docs.kilocode.ai)
* 🎯 [Agent Roles Guide](https://kilocode.ai/best-practices)
* 💡 [Integration Examples](https://github.com/bitrouter/kilocode-integration)
* 💬 [Discord Community](https://discord.gg/G3zVrZDa5C)
# Openclaw (/docs/cookbook/integration/openclaw)
Openclaw Integration [#openclaw-integration]
Quick Start [#quick-start]
```bash
# 1. Start BitRouter
bitrouter serve
# 2. Install Openclaw plugin
openclaw plugins install bitrouter
# 3. Configure and launch
openclaw config set provider bitrouter
openclaw start --provider bitrouter
```
What You Get [#what-you-get]
* ✅ **20+ messaging platforms** - WhatsApp, Telegram, Slack, Discord, etc.
* ✅ **Multi-provider routing** - Optimize models per platform
* ✅ **Native plugin support** - Seamless BitRouter integration
* ✅ **Isolated workspaces** - Separate contexts per channel
* ✅ **Cost tracking** - Monitor spending across all platforms
Installation [#installation]
Prerequisites [#prerequisites]
```bash
# Install Openclaw
npm install -g openclaw@latest
# Quick setup
openclaw onboard --install-daemon
```
Connect to BitRouter [#connect-to-bitrouter]
Choose your method:
Option 1: Native Plugin (Recommended) [#option-1-native-plugin-recommended]
```bash
openclaw plugins install bitrouter
openclaw config set provider bitrouter
openclaw config set bitrouter.url http://localhost:8787
openclaw start
```
Option 2: ACP Integration [#option-2-acp-integration]
```bash
openclaw config set protocol acp
openclaw config set acp.endpoint http://localhost:8787
openclaw acp
```
Option 3: Direct API [#option-3-direct-api]
```bash
openclaw config set api.base http://localhost:8787
openclaw start
```
Essential Configuration [#essential-configuration]
Platform-Specific Routing [#platform-specific-routing]
```yaml
# ~/.bitrouter/config.yaml
routes:
# WhatsApp - conversational
- match: "openclaw/whatsapp/*"
provider: anthropic
model: claude-3-5-haiku-latest
options:
temperature: 0.8
# Slack - professional
- match: "openclaw/slack/*"
provider: openai
model: gpt-4o
options:
temperature: 0.3
# Discord - community
- match: "openclaw/discord/*"
provider: deepseek
model: deepseek-chat
# Telegram - quick
- match: "openclaw/telegram/*"
provider: google
model: gemini-2.0-flash-exp
```
Workspace Isolation [#workspace-isolation]
```yaml
workspaces:
- name: "enterprise-slack"
match: "openclaw/slack/enterprise/*"
provider: anthropic
model: claude-3-5-sonnet-latest
guardrails:
- data_isolation
- audit_logging
- name: "public-discord"
match: "openclaw/discord/public/*"
provider: openai
model: gpt-4o-mini
rate_limits:
requests_per_minute: 10
```
Skills Integration [#skills-integration]
```yaml
skills:
source: clawhub.ai
routing:
- skill: "code-review"
route: "openclaw/skills/review"
provider: anthropic
model: claude-3-5-sonnet-latest
- skill: "debug-assistance"
route: "openclaw/skills/debug"
provider: openai
model: gpt-4o
```
Common Recipes [#common-recipes]
Recipe: Multi-Channel Bot [#recipe-multi-channel-bot]
```yaml
platforms:
whatsapp:
route: "openclaw/whatsapp"
qr_code: true
slack:
route: "openclaw/slack"
oauth: true
telegram:
route: "openclaw/telegram"
bot_token: true
```
Recipe: Voice Support [#recipe-voice-support]
```yaml
voice:
wake_word: "hey openclaw"
transcription:
route: "openclaw/voice/transcribe"
model: whisper-large-v3
synthesis:
route: "openclaw/voice/synthesize"
model: tts-1-hd
```
Recipe: Live Canvas [#recipe-live-canvas]
```yaml
canvas:
enabled: true
route: "openclaw/canvas/*"
features:
- collaborative_editing
- real_time_sync
- version_control
```
Platform Setup [#platform-setup]
WhatsApp Business [#whatsapp-business]
```bash
# Connect via QR code
openclaw connect whatsapp
# Scan QR code with phone
```
Slack Integration [#slack-integration]
```bash
# OAuth setup
openclaw connect slack --workspace YOUR_WORKSPACE
# Follow OAuth flow
```
Discord Bot [#discord-bot]
```bash
# Bot token setup
openclaw connect discord --token YOUR_BOT_TOKEN
```
Monitoring [#monitoring]
Channel Activity [#channel-activity]
```bash
# View all channels
bitrouter dashboard --agent openclaw
# Channel metrics
bitrouter metrics --agent openclaw --channel whatsapp
# Export analytics
bitrouter export analytics --agent openclaw --format csv
```
Cost Tracking [#cost-tracking]
```bash
# Platform breakdown
bitrouter costs breakdown --group-by platform
# Set budgets
bitrouter budget set --platform whatsapp --daily 10
bitrouter budget set --platform slack --daily 50
```
Troubleshooting [#troubleshooting]
🔴 Connection Issues [#-connection-issues]
```bash
# Check BitRouter
curl http://localhost:8787/health
# Verify Openclaw
openclaw config show
# Test connection
openclaw test connection --provider bitrouter
```
🟡 Platform Failures [#-platform-failures]
```bash
# Debug platform
openclaw debug whatsapp
# Check logs
bitrouter logs --filter openclaw
# Verify credentials
openclaw platforms verify
```
🔵 Message Routing [#-message-routing]
```bash
# Trace message
bitrouter trace --message-id
# Test route
bitrouter routes test "openclaw/whatsapp/message"
# Monitor live
bitrouter monitor --agent openclaw --live
```
Advanced Features [#advanced-features]
Multi-Agent Routing [#multi-agent-routing]
```yaml
multi_agent:
- pattern: "openclaw/*/code/*"
agent: claude-code
- pattern: "openclaw/*/docs/*"
agent: opencode
```
Custom Skills [#custom-skills]
```bash
# Add skill
openclaw skills add custom-skill
# Configure routing
openclaw skills config custom-skill \
--route "openclaw/skills/custom" \
--provider "anthropic"
```
Learn More [#learn-more]
* 📚 [Openclaw Documentation](https://docs.openclaw.ai)
* 🔌 [BitRouter Plugin](https://github.com/bitrouter/bitrouter-openclaw)
* 🛒 [ClawHub Marketplace](https://clawhub.ai)
* 💬 [Discord Community](https://discord.gg/G3zVrZDa5C)
# Opencode (/docs/cookbook/integration/opencode)
Opencode Integration [#opencode-integration]
Quick Start [#quick-start]
```bash
# 1. Start BitRouter
bitrouter serve
# 2. Configure Opencode for BitRouter
opencode config provider bitrouter
opencode config set bitrouter.url http://localhost:8787
# 3. Launch Opencode
opencode
```
What You Get [#what-you-get]
* ✅ **75+ provider support** - All through BitRouter's unified interface
* ✅ **Terminal-first design** - Clean TUI with BitRouter integration
* ✅ **Provider switching** - Seamlessly swap between models
* ✅ **Session persistence** - Save/restore with JSONL format
* ✅ **LSP integration** - Enhanced code understanding
Installation [#installation]
Prerequisites [#prerequisites]
```bash
# Install Opencode
curl -fsSL https://opencode.ai/install | bash
# Or via package manager
npm install -g @opencode/cli
# brew install opencode
```
Connect to BitRouter [#connect-to-bitrouter]
Choose your mode:
Option 1: Native Integration [#option-1-native-integration]
```bash
opencode config provider bitrouter
opencode config set bitrouter.url http://localhost:8787
opencode
```
Option 2: BYOK Mode [#option-2-byok-mode]
```bash
opencode config mode byok
opencode config set api.base http://localhost:8787
opencode
```
Option 3: Zen + BitRouter [#option-3-zen--bitrouter]
```bash
opencode config mode zen
opencode config set zen.proxy http://localhost:8787
opencode --hybrid-routing
```
Essential Configuration [#essential-configuration]
Provider-Agnostic Routing [#provider-agnostic-routing]
```yaml
# ~/.bitrouter/config.yaml
routes:
# Main coding tasks
- match: "opencode/code/*"
provider: anthropic
model: claude-3-5-sonnet-latest
# Quick operations
- match: "opencode/quick/*"
provider: openai
model: gpt-4o-mini
# Local models via Ollama
- match: "opencode/local/*"
provider: ollama
model: codellama:34b
endpoint: http://localhost:11434
```
Multi-Session Support [#multi-session-support]
```yaml
sessions:
opencode:
persistence: true
storage: ~/.opencode/sessions
features:
auto_save: true
branching: true
undo_redo: true
sharing: true
routing:
new: "opencode/session/new"
restore: "opencode/session/restore"
```
LSP Integration [#lsp-integration]
```yaml
lsp:
enabled: true
servers:
- language: python
command: pylsp
route: "opencode/lsp/python"
- language: typescript
command: typescript-language-server
route: "opencode/lsp/typescript"
- language: rust
command: rust-analyzer
route: "opencode/lsp/rust"
```
Common Recipes [#common-recipes]
Recipe: Cost-Optimized Development [#recipe-cost-optimized-development]
```yaml
routes:
- match: "opencode/*"
rules:
- if: task_type == "simple"
model: gpt-4o-mini
- if: task_type == "complex"
model: claude-3-5-sonnet-latest
```
Recipe: Multi-Provider Fallback [#recipe-multi-provider-fallback]
```yaml
routes:
- match: "opencode/*"
provider: anthropic
fallback:
- openai
- deepseek
- ollama
```
Recipe: Zen Mode Integration [#recipe-zen-mode-integration]
```yaml
zen:
enabled: true
models:
- name: "zen-coder"
route: "opencode/zen/coder"
fallback: "claude-3-5-sonnet-latest"
```
TUI Features [#tui-features]
Enhanced Terminal Interface [#enhanced-terminal-interface]
```yaml
tui:
opencode:
theme: catppuccin
features:
- syntax_highlighting
- multi_pane
- session_tabs
routing:
interactive: "opencode/tui/*"
```
Monitoring [#monitoring]
Session Analytics [#session-analytics]
```bash
# View Opencode sessions
bitrouter sessions list --agent opencode
# Monitor active session
bitrouter monitor --agent opencode --session
# Export session data
bitrouter export session --agent opencode --format json
```
Provider Performance [#provider-performance]
```bash
# Benchmark providers
bitrouter providers benchmark
# Provider switching stats
bitrouter providers stats --agent opencode
# Cost breakdown
bitrouter costs breakdown --agent opencode
```
Troubleshooting [#troubleshooting]
🔴 Connection Issues [#-connection-issues]
```bash
# Check BitRouter
curl http://localhost:8787/health
# Verify Opencode config
opencode config show
# Test connection
opencode test connection --provider bitrouter
```
🟡 Provider Switching [#-provider-switching]
```bash
# List providers
bitrouter providers list
# Test routing
bitrouter test route "opencode/test"
# Reset config
opencode config reset providers
```
🔵 Session Problems [#-session-problems]
```bash
# Check storage
ls -la ~/.opencode/sessions
# Clear corrupted
opencode sessions clear --corrupted
# Verify format
opencode sessions validate
```
Advanced Features [#advanced-features]
Undo/Redo System [#undoredo-system]
```yaml
history:
opencode:
enabled: true
max_depth: 100
routing:
undo: "opencode/history/undo"
redo: "opencode/history/redo"
```
MCP Integration [#mcp-integration]
```yaml
mcp:
opencode:
servers:
- name: filesystem
route: "opencode/mcp/fs"
- name: github
route: "opencode/mcp/github"
```
Custom Providers [#custom-providers]
```yaml
custom_providers:
opencode:
- name: "internal-llm"
endpoint: "https://llm.company.com"
route: "opencode/custom/*"
auth: bearer
```
Learn More [#learn-more]
* 📚 [Opencode Documentation](https://docs.opencode.ai)
* 🔄 [Provider Guide](https://opencode.ai/providers)
* 💡 [Integration Examples](https://github.com/bitrouter/opencode-integration)
* 💬 [Discord Community](https://discord.gg/G3zVrZDa5C)
# Pi Agent (/docs/cookbook/integration/pi)
Pi Agent Integration [#pi-agent-integration]
Quick Start [#quick-start]
```bash
# 1. Start BitRouter
bitrouter serve
# 2. Configure Pi extension
pi config set ai.provider custom
pi config set ai.baseUrl http://localhost:8787
# 3. Launch Pi
pi
```
What You Get [#what-you-get]
* ✅ **Minimal & extensible** - Terminal-first with BitRouter routing
* ✅ **Extension system** - Custom tools and workflows through BitRouter
* ✅ **Session persistence** - Tree-structured JSONL sessions
* ✅ **Smart compaction** - Context management with cheaper models
* ✅ **Skills system** - On-demand capabilities via BitRouter
Installation [#installation]
Prerequisites [#prerequisites]
```bash
# Install Pi (choose one)
npm install -g @mariozechner/pi-coding-agent
# Clone from GitHub: github.com/earendil-works/pi
```
Connect to BitRouter [#connect-to-bitrouter]
Choose your method:
Option 1: Extension-Based [#option-1-extension-based]
```typescript
// pi-bitrouter-extension.ts
import { Extension } from '@earendil-works/pi-coding-agent';
export class BitRouterExtension extends Extension {
name = 'bitrouter';
async initialize(pi) {
pi.config.set('ai.provider', 'custom');
pi.config.set('ai.baseUrl', 'http://localhost:8787');
}
}
```
Option 2: Configuration File [#option-2-configuration-file]
```javascript
// ~/.pi/config.js
module.exports = {
ai: {
provider: 'custom',
baseUrl: 'http://localhost:8787',
model: 'auto', // Let BitRouter handle routing
},
extensions: ['@pi/bitrouter-extension']
};
```
Option 3: Environment Variables [#option-3-environment-variables]
```bash
export PI_AI_PROVIDER=custom
export PI_AI_BASE_URL=http://localhost:8787
pi
```
Essential Configuration [#essential-configuration]
Smart Task Routing [#smart-task-routing]
```yaml
# ~/.bitrouter/config.yaml
routes:
# Main coding operations
- match: "pi/code/*"
provider: anthropic
model: claude-3-5-sonnet-latest
# Quick operations
- match: "pi/quick/*"
provider: openai
model: gpt-4o-mini
# Complex tasks
- match: "pi/complex/*"
provider: openai
model: o1-preview
# Context compaction
- match: "pi/compaction/*"
provider: anthropic
model: claude-3-5-haiku-latest
```
Compaction & Context [#compaction--context]
```yaml
compaction:
pi:
enabled: true
strategy:
type: custom
route: "pi/compaction/*"
model: claude-3-5-haiku-latest
thresholds:
context_usage: 0.8
message_count: 50
preserve:
- code_blocks
- error_messages
- user_instructions
```
Session Management [#session-management]
```yaml
sessions:
pi:
structure: tree
persistence: jsonl
routing:
main: "pi/session/main/*"
branches: "pi/session/branch/*"
features:
auto_branch: true
session_replay: true
storage:
path: ~/.pi/sessions/
compression: true
```
Common Recipes [#common-recipes]
Recipe: Extension Development [#recipe-extension-development]
```typescript
// Enhanced BitRouter extension
export class BitRouterEnhanced extends Extension {
name = 'bitrouter-enhanced';
tools = [
{
name: 'route_optimize',
description: 'Optimize routing for task',
execute: async ({ task_type }) => {
const route = `pi/${task_type}/*`;
await this.pi.config.set('bitrouter.route', route);
return `Routing optimized for ${task_type}`;
}
}
];
}
```
Recipe: Skills Integration [#recipe-skills-integration]
```yaml
# skill.yaml
name: bitrouter-coding
description: Enhanced coding with BitRouter
instructions: |
Use BitRouter's intelligent routing:
- Complex algorithms: route through 'pi/complex'
- Quick edits: route through 'pi/quick'
- Documentation: route through 'pi/docs'
tools: [file_operations, bitrouter_routing]
```
Recipe: Package Distribution [#recipe-package-distribution]
```json
// package.json
{
"name": "@custom/pi-bitrouter",
"version": "1.0.0",
"pi": {
"extensions": ["./dist/extension.js"],
"skills": ["./skills"],
"themes": ["./themes/bitrouter.json"]
}
}
```
Theme Customization [#theme-customization]
BitRouter Status Theme [#bitrouter-status-theme]
```typescript
export const bitrouterTheme = {
name: 'bitrouter-status',
statusBar: {
left: ['mode', 'model'],
right: ['cost', 'latency', 'provider']
},
colors: {
primary: '#00A67E',
success: '#10B981',
warning: '#F59E0B'
},
indicators: {
routing: '🔀',
cached: '💾',
fallback: '🔄'
}
};
```
Monitoring [#monitoring]
Session Analytics [#session-analytics]
```bash
# Monitor Pi sessions
bitrouter sessions list --agent pi
# Real-time metrics
bitrouter monitor --agent pi --live
# Export analytics
bitrouter export analytics --agent pi --format csv
```
Cost Tracking [#cost-tracking]
```bash
# Pi agent costs
bitrouter costs breakdown --agent pi
# Set limits
bitrouter budget set --agent pi --daily 10.00
# Generate report
bitrouter report generate --agent pi --period week
```
Troubleshooting [#troubleshooting]
🔴 Connection Issues [#-connection-issues]
```bash
# Check BitRouter
curl http://localhost:8787/health
# Pi configuration
pi config show
# Test connection
pi debug connection --provider custom
```
🟡 Extension Problems [#-extension-problems]
```bash
# List extensions
pi extensions list
# Reload extensions
pi extensions reload
# Debug extension
pi debug extension bitrouter
```
🔵 Session Persistence [#-session-persistence]
```bash
# Check session storage
ls -la ~/.pi/sessions/
# Validate JSONL
pi session validate
# Clear corrupted
pi session clear --corrupted
```
Advanced Features [#advanced-features]
Sub-Agent Orchestration [#sub-agent-orchestration]
```typescript
export class SubAgentExtension extends Extension {
async createSubAgent(task) {
return {
name: `pi-sub-${task.id}`,
route: `pi/subagent/${task.type}/*`,
model: this.selectModelForTask(task)
};
}
}
```
Plan Mode Integration [#plan-mode-integration]
```yaml
plan_mode:
pi:
enabled: true
route: "pi/planning/*"
features:
- auto_planning
- step_validation
- progress_tracking
model_selection:
planning: claude-3-5-sonnet-latest
execution: gpt-4o
```
Learn More [#learn-more]
* 📚 [Pi Documentation](https://pi.dev/docs)
* 🔧 [GitHub Repository](https://github.com/earendil-works/pi)
* 📦 [Package Registry](https://npmjs.com/search?q=pi-coding-agent)
* 💬 [Discord Community](https://discord.gg/G3zVrZDa5C)
# Migration Guides (/docs/cookbook/migration)
Migration Guides [#migration-guides]
Learn how to migrate your existing LLM routing solution to BitRouter with minimal disruption.
Migrate Quickly with Agent Skills [#migrate-quickly-with-agent-skills]
The fastest way to migrate is to let an agent do it for you. The **BitRouter skill** in Claude Code can detect your current configuration, rewrite your `baseURL` and API key, and validate the result automatically.
Install the agent skills package:
```
npx skills add BitRouterAI/agent-skills
```
Then describe what you're migrating from — for example: *"migrate my OpenRouter setup to BitRouter"*. The agent handles the rest.
General Migration Guide [#general-migration-guide]
Regardless of your current provider, the core change is the same: point your existing OpenAI-compatible client at BitRouter by updating two values.
1. Update your base URL [#1-update-your-base-url]
```
# Cloud
https://api.bitrouter.ai/v1
# Self-hosted
http://localhost:8787/v1
```
2. Update your API key [#2-update-your-api-key]
```bash
BITROUTER_API_KEY=your-key-here
```
Set this as the bearer token (or the `api_key` field) wherever your current provider key lives.
3. Model names stay the same [#3-model-names-stay-the-same]
BitRouter uses the same model IDs as OpenAI-compatible APIs (`gpt-4o`, `claude-3-5-sonnet-20241022`, etc.) — no renaming required.
4. Verify the switch [#4-verify-the-switch]
```bash
curl https://api.bitrouter.ai/v1/chat/completions \
-H "Authorization: Bearer $BITROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}'
```
For provider-specific steps and edge cases, see the guides below.
Available Migration Guides [#available-migration-guides]
Migrate from OpenRouter [#migrate-from-openrouter]
Complete guide for teams using OpenRouter who want to switch to BitRouter for better performance, self-hosting options, and agent-native features.
Migrate from LiteLLM [#migrate-from-litellm]
Step-by-step migration from LiteLLM's Python SDK or Proxy Server to BitRouter's high-performance Rust binary with zero dependencies.
Why Migrate to BitRouter? [#why-migrate-to-bitrouter]
* **Performance**: \<10ms routing overhead vs 25-100ms for alternatives
* **Simplicity**: Single binary, no databases or containers required
* **Agent-Native**: Built-in MCP/ACP gateway, guardrails, and skills
* **Flexibility**: Self-host or cloud, BYOK or pay-per-use
* **Open Source**: Apache 2.0 license, permissionless usage
Need Help? [#need-help]
* Join our [Discord community](https://discord.gg/G3zVrZDa5C) for migration support
* Open an [issue on GitHub](https://github.com/bitrouter/bitrouter/issues)
* Contact [contact@bitrouter.ai](mailto:contact@bitrouter.ai) for enterprise migrations
# Migrate from LiteLLM (/docs/cookbook/migration/litellm)
import { Callout } from 'fumadocs-ui/components/callout';
import { Cards, Card } from 'fumadocs-ui/components/card';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
Migrating from LiteLLM to BitRouter [#migrating-from-litellm-to-bitrouter]
LiteLLM is a Python SDK and self-hosted proxy for unifying access to 100+ LLM providers. BitRouter solves the same problem from a different angle: an **agent-native proxy** with a single OpenAI-compatible surface — runnable as a local binary (BYOK, no infra) or as a hosted endpoint with autonomous agent payments. This guide is for teams whose workload has shifted from backend services to agent runtimes and want a leaner, agent-first surface.
Why migrate? [#why-migrate]
| | LiteLLM Proxy | BitRouter |
| -------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| **Runtime** | Python | Rust (single static binary) |
| **Production deps** | Postgres + Redis + Docker/K8s | None |
| **Deployment modes** | Self-hosted only | Local binary **or** hosted (`cloud.bitrouter.ai`) — same OpenAI-compatible endpoint |
| **Agentic auth & payment** | None | x402 / MPP autonomous payment (cloud mode) |
| **Design focus** | All-in-one LLM gateway: admin UI, virtual keys, budgets, with agent gateways added alongside | Agent-first proxy: MCP / ACP / Skills, agent firewall, agentic payment as the core surface |
| **Agent protocol surface** | MCP, A2A, Skills, CLI — bolted onto the horizontal gateway | MCP, ACP, Skills, CLI — the product, not an add-on |
| **License** | MIT (SDK) / paid enterprise tier | Apache 2.0 throughout |
Two things worth highlighting [#two-things-worth-highlighting]
1. Cloud and local share the same surface [#1-cloud-and-local-share-the-same-surface]
With LiteLLM, the proxy is something you operate. With BitRouter, **the hosted cloud and local binary expose the same OpenAI-compatible endpoint** — you can start local during development, then point at `cloud.bitrouter.ai` for production (or vice versa) without changing client code. The CLI, the wizard, and Agent Skills all work in either mode; toggle with one keypress in the setup TUI. See the [Quick Start](/docs/guides/overview/quickstart) for both flows.
This matters when your agent should *pay per request* without you provisioning keys for it — Cloud mode supports [x402 / MPP autonomous payments](/docs/guides/features/payment), which LiteLLM has no equivalent for.
2. Agent-native, not all-in-one [#2-agent-native-not-all-in-one]
LiteLLM has shipped MCP, A2A, Skills, and a CLI alongside its horizontal LLM gateway — virtual keys, team budgets, spend dashboards, admin UI all included. BitRouter inverts that: agent primitives *are* the product, the team-admin stack is intentionally minimal. What you get on the BitRouter surface:
* [MCP gateway](/docs/guides/features/mcp) — proxy MCP servers so agents discover tools across hosts.
* [ACP gateway](/docs/guides/features/acp) — first-class support for the Agent Client Protocol used by Claude Code, Codex, OpenCode, and others.
* [Guardrails](/docs/guides/features/guardrails) — agent firewall on the proxy hop: inspect, redact, or block inline.
* [Observability](/docs/guides/features/observability) — built-in spend and request tracing, no external collector required.
* Agent Skills gateway (coming soon) — install and route capabilities by skill, not by raw model name.
* [Headless CLI](/docs/guides/features/cli) — TUI wizard plus scriptable commands for setup and ops.
* [Agentic auth & payment](/docs/guides/features/payment) — x402 / MPP so an agent can pay per request without you provisioning a key for it. LiteLLM has no equivalent.
If you depend on LiteLLM's team-admin UI, virtual keys, and per-user budgets, LiteLLM is still the better fit. If you're building agents — especially agents that should transact autonomously — BitRouter is.
Migration paths [#migration-paths]
From the LiteLLM Python SDK [#from-the-litellm-python-sdk]
LiteLLM as a library becomes a BitRouter base URL swap on the standard OpenAI SDK:
```python
from litellm import completion
response = completion(
model="openai/gpt-4o",
messages=[{"role": "user", "content": "Hello"}],
api_key="sk-...",
)
```
```python
import openai
# Local: `bitrouter` (BYOK via env vars) — see /docs/guides/overview/quickstart
# Cloud: base_url="https://cloud.bitrouter.ai/v1", api_key=$BITROUTER_API_KEY
client = openai.OpenAI(
base_url="http://localhost:8787/v1",
api_key="not-used-in-local-byok",
)
response = client.chat.completions.create(
model="openai/gpt-4o",
messages=[{"role": "user", "content": "Hello"}],
)
```
Fallbacks and provider selection that you'd configure with `litellm.Router` move into BitRouter's [routing presets](/docs/guides/features/presets) and [model fallback rules](/docs/guides/routing/model-fallback) — declared once, not per call site.
From the LiteLLM Proxy [#from-the-litellm-proxy]
The proxy migration replaces the Python process + Postgres + Redis with a single binary. Install and launch:
```bash
docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=pass postgres
docker run -d -p 6379:6379 redis
pip install 'litellm[proxy]'
litellm --config config.yaml --port 8000
```
```bash
# Install (curl, npm, brew, or cargo — see Quick Start)
curl -fsSL https://bitrouter.ai/install.sh | sh
# Set provider keys; BitRouter auto-detects on start
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
# Interactive wizard (Cloud or local); default local serves on :8787
bitrouter
```
To skip the local proxy entirely, point clients at `https://cloud.bitrouter.ai/v1` with a BitRouter API key — no binary, no infra. Same endpoint shape.
Feature mapping [#feature-mapping]
| LiteLLM concept | BitRouter equivalent | Docs |
| ---------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `model_list` in `config.yaml` | Provider keys + routing presets | [Presets](/docs/guides/features/presets) |
| `router_settings` (retries, fallback) | Model fallback rules | [Model fallback](/docs/guides/routing/model-fallback) |
| `routing_strategy` (least-busy, latency) | Provider selection | [Provider selection](/docs/guides/routing/provider-selection) |
| `cache` (Redis/DynamoDB backed) | Not built into the proxy — handle in app/edge if needed | — |
| Virtual keys + budgets + admin UI | Workspace keys (cloud); env-var keys (local) | [BYOK](/docs/guides/features/byok), [Workspaces](/docs/guides/features/workspaces) |
| Guardrails / PII / content filter | Agent firewall on the proxy hop | [Guardrails](/docs/guides/features/guardrails) |
| Callbacks (Langfuse, Datadog, etc.) | Built-in spend + request logs; export hooks planned | [Observability](/docs/guides/features/observability) |
| MCP Gateway | MCP gateway | [MCP](/docs/guides/features/mcp) |
| A2A Agent Gateway | ACP gateway | [ACP](/docs/guides/features/acp) |
| Skills Gateway / `/skills` endpoint | Skills gateway with [agentskills.io](https://agentskills.io) registry | [Agent Skills](/docs/guides/features/agentskills) |
| LiteLLM Proxy CLI | `bitrouter` CLI / TUI | [Headless CLI](/docs/guides/features/cli) |
| — (no equivalent) | Autonomous agent payment (x402 / MPP) | [Payment](/docs/guides/features/payment) |
What BitRouter intentionally doesn't ship [#what-bitrouter-intentionally-doesnt-ship]
To set expectations honestly: BitRouter does not ship a built-in admin UI for team/user budgets, virtual-key generation by API, or a spend analytics dashboard at parity with LiteLLM Enterprise. Per-workspace key scoping in cloud mode and env-var-scoped keys in local mode cover the common cases, but if your migration depends on per-user virtual keys with quotas enforced inside the proxy, plan for that gap or stay on LiteLLM for those workloads.
Migration checklist [#migration-checklist]
**Before migration**
* [ ] List the providers and models you actually use (skip the rest)
* [ ] Note any custom callbacks/middleware — see if a [guardrail rule](/docs/guides/features/guardrails) covers it
* [ ] Decide cloud vs. local (or both — they share the endpoint)
**Migration**
* [ ] Install the BitRouter CLI ([Quick Start](/docs/guides/overview/quickstart))
* [ ] Export provider keys, or paste them into the cloud dashboard (sealed-box encrypted)
* [ ] Update client `base_url` to `http://localhost:8787/v1` (local) or `https://cloud.bitrouter.ai/v1` (cloud)
* [ ] Verify with a sample request
* [ ] Decommission Postgres / Redis if local-only setup is sufficient
Next steps [#next-steps]
Get help [#get-help]
* **Discord**: [Join the community](https://discord.gg/G3zVrZDa5C) for migration support
* **GitHub**: [Open an issue](https://github.com/bitrouter/bitrouter/issues)
* **Email**: [contact@bitrouter.ai](mailto:contact@bitrouter.ai) for enterprise migration assistance
# Migrate from OpenRouter (/docs/cookbook/migration/openrouter)
import { Cards, Card } from 'fumadocs-ui/components/card';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
Migrating from OpenRouter to BitRouter [#migrating-from-openrouter-to-bitrouter]
This guide walks you through migrating your existing OpenRouter integration to BitRouter, highlighting key differences and advantages.
Why Migrate? [#why-migrate]
BitRouter offers several advantages over OpenRouter for agent workloads:
| Feature | OpenRouter | BitRouter |
| ------------------ | ----------------------------- | ---------------------------------------------- |
| **Deployment** | Cloud-only (closed-source) | Self-host or cloud (Apache 2.0) |
| **Platform Fee** | 5.5% via Stripe | 2% via stablecoins · 5% via Stripe |
| **Agent Features** | Basic routing | Headless CLI, agentic payment, MCP/ACP gateway |
| **Access** | Account registration required | No registration required |
Migration Path [#migration-path]
Step 1: Get your BitRouter API key [#step-1-get-your-bitrouter-api-key]
**Option A: Headless CLI (recommended)**
Install the CLI and sign in — `bitrouter auth login` runs the RFC 8628 device-code flow, opens an approval URL in your browser, and persists the resulting OAuth credential (auto-refreshed) under `$XDG_DATA_HOME/bitrouter/account-credentials.json`. After that, every request through the `bitrouter` provider is authenticated automatically — no API key in your config:
```bash
npm install -g bitrouter
bitrouter auth login
```
Inspect the local session with `bitrouter auth whoami`, and manage account-level resources (API keys, usage, billing, policies, BYOK, OAuth clients) with `bitrouter cloud --help`.
**Option B: Dashboard**
Sign up at [cloud.bitrouter.ai](https://cloud.bitrouter.ai) and copy your API key from the dashboard.
Step 2: Update base URL and API key [#step-2-update-base-url-and-api-key]
That's the full migration. Replace your OpenRouter endpoint and key with BitRouter's:
```python
# Before (OpenRouter)
client = openai.OpenAI(
base_url="https://openrouter.ai/api/v1",
api_key=OPENROUTER_API_KEY,
)
# After (BitRouter)
client = openai.OpenAI(
base_url="https://api.bitrouter.ai/v1",
api_key=BITROUTER_API_KEY,
)
```
```javascript
// Before (OpenRouter)
const client = new OpenAI({
baseURL: 'https://openrouter.ai/api/v1',
apiKey: OPENROUTER_API_KEY,
});
// After (BitRouter)
const client = new OpenAI({
baseURL: 'https://api.bitrouter.ai/v1',
apiKey: BITROUTER_API_KEY,
});
```
```bash
# Before (OpenRouter)
curl https://openrouter.ai/api/v1/chat/completions \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "openai/gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'
# After (BitRouter)
curl https://api.bitrouter.ai/v1/chat/completions \
-H "Authorization: Bearer $BITROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "openai/gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'
```
Headers to Remove [#headers-to-remove]
If your OpenRouter integration sets any of these headers, you can safely drop them:
| OpenRouter header | Status in BitRouter |
| ----------------- | ---------------------------------------------------------- |
| `HTTP-Referer` | Not used |
| `X-Title` | Not used |
| `transforms` | Not used — guardrails are configured server-side |
| `route` | Not used — provider routing is configured in the dashboard |
Next Steps [#next-steps]
Need Help? [#need-help]
* **Discord**: [Join our community](https://discord.gg/G3zVrZDa5C) for migration support
* **GitHub**: [Report issues](https://github.com/bitrouter/bitrouter/issues) or contribute
* **Email**: [contact@bitrouter.ai](mailto:contact@bitrouter.ai) for enterprise migration assistance
# Create message (/docs/api-reference/anthropic-compatible/createMessage)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Creates a message using the Anthropic Messages API format. Drop-in replacement for the Anthropic API.
When `stream: true`, the response is sent as Server-Sent Events (SSE). Each event has a `type` field indicating the event kind (`message_start`, `content_block_delta`, `message_delta`, `message_stop`).
# Get BYOK sealed-box public key (/docs/api-reference/byok/getEncryptionPubkey)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Returns the node's current X25519 sealed-box public key plus its `kek_id` fingerprint. The console encrypts the user's provider key against this pubkey before storing the ciphertext — the node never sees plaintext on the write path.
Honors `If-None-Match: ""` for cheap caching, returning `304 Not Modified` when the cached fingerprint still matches.
# List available models (/docs/api-reference/discovery/listModels)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Returns all models available across configured providers. Supports optional query filters for provider, model ID substring, and modality.
# List providers (/docs/api-reference/discovery/listProviders)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Public registry of providers the node knows about, sourced from the upstream `bitrouter-providers` builtins. Used by the console to render the BYOK page without hard-coding the list.
# Generate content (Google) (/docs/api-reference/google-compatible/googleGenerateContent)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Generates content using the Google Generative Language API format. Drop-in replacement for `generativelanguage.googleapis.com/v1beta`.
The model id and streaming verb are both encoded in the `model_action` path segment — for example `gemini-2.0-flash:generateContent` (synchronous) or `gemini-2.0-flash:streamGenerateContent` (SSE). The cloud injects the model id into the request body before dispatching, so callers can use the same URL convention as Google's own API.
# Liveness check (/docs/api-reference/health/ping)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Returns `200 OK` with an empty body if the node is up.
# Prometheus metrics scrape (/docs/api-reference/observability/getMetrics)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Returns Prometheus-format metrics for ingestion by a scraper. Not intended for human callers — point Prometheus, Grafana Agent, or any OpenMetrics-compatible collector at this endpoint.
Responds `404 Not Found` when the node was built or configured without a metrics renderer; scrapers can use that as a feature probe.
# Bind a policy to a principal (/docs/api-reference/management/bindPolicy)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Attaches the policy to a principal (account / api\_key / oauth\_token / oauth\_client). The engine sums all bindings most-restrictive-wins at request time.
*Requires the `policy:write` scope.*
# Create a Stripe Checkout Session (/docs/api-reference/management/createCheckoutSession)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Creates a Stripe Checkout Session to buy credits. Returns the hosted URL the user must visit to complete payment.
*Requires the `billing:write` scope.*
# Create a policy (/docs/api-reference/management/createPolicy)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Create a `budget` / `rate_limit` / `guardrail` / `preset` policy. The `spec` body must match the requested `kind`.
*Requires the `policy:write` scope.*
# Delete a BYOK provider key (/docs/api-reference/management/deleteByokKey)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
*Requires the `byok:write` scope.*
# Delete an OAuth client (/docs/api-reference/management/deleteOauthClient)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
*Requires the `clients:write` scope.*
# Delete a policy and its bindings (/docs/api-reference/management/deletePolicy)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
*Requires the `policy:write` scope.*
# Credit account balance (/docs/api-reference/management/getBillingBalance)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Returns the raw balance, pending debits, and effective available amount in micro-USD.
*Requires the `billing:read` scope.*
# Aggregate spend / tokens for a window (/docs/api-reference/management/getUsageAggregate)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Sums `usage` / `pending_debit_recovery` ledger entries and the `requests` rows over the window. Defaults to the last 30 days.
*Requires the `usage:read` scope.*
# List API keys for the calling account (/docs/api-reference/management/listApiKeys)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Account-scoped list of brk\_ API keys. Never returns the secret.
*Requires the `keys:read` scope.*
# List BYOK provider keys (/docs/api-reference/management/listByokKeys)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Metadata-only — never returns the sealed ciphertext.
*Requires the `byok:read` scope.*
# List the caller's OAuth clients (/docs/api-reference/management/listOauthClients)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Never returns the `client_secret_hash`.
*Requires the `clients:read` scope.*
# List account policies (/docs/api-reference/management/listPolicies)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
*Requires the `policy:read` scope.*
# Paginated request history (/docs/api-reference/management/listRequests)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Per-request metadata. Never includes the prompt or response body.
*Requires the `usage:read` scope.*
# Mint a new API key (/docs/api-reference/management/mintApiKey)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Mint a brk\_ API key. Returns the plaintext token exactly once.
The requested `scopes` must be a subset of the caller's effective scopes — no upscaling (RFC 6749 §3.3).
*Requires the `keys:write` scope.*
# Register a new OAuth client (/docs/api-reference/management/registerOauthClient)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Confidential clients receive the freshly minted `client_secret` once in the response — the cloud retains only the hash.
*Requires the `clients:write` scope.*
# Revoke an API key (/docs/api-reference/management/revokeApiKey)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Stamps `revoked_at` on the row. Subsequent verifies fail with 401.
*Requires the `keys:write` scope.*
# Remove a policy binding (/docs/api-reference/management/unbindPolicy)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
*Requires the `policy:write` scope.*
# Update an OAuth client (/docs/api-reference/management/updateOauthClient)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Mutate the client's name, redirect URIs, allowed scopes, or allowed grant types. Each field is optional.
*Requires the `clients:write` scope.*
# Update a policy's name or spec (/docs/api-reference/management/updatePolicy)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
In-place update of a policy's `name` and / or `spec`. Kind changes are not supported — recreate the policy if the kind needs to differ.
*Requires the `policy:write` scope.*
# Upsert a BYOK provider key (/docs/api-reference/management/upsertByokKey)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Stores a sealed-box ciphertext for one provider. Refuses any payload sealed against a `kek_id` other than the cloud's current encryption pubkey (`/v1/byok/encryption-pubkey`).
*Requires the `byok:write` scope.*
# Create chat completion (/docs/api-reference/openai-compatible/createChatCompletion)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Creates a chat completion for the given messages. Drop-in replacement for the OpenAI Chat Completions API — accepts the same request schema and returns the same response format, including `usage` with token counts.
The router resolves the requested model to an upstream provider, forwards the request, and returns the response. Supports both synchronous and streaming modes.
When `stream: true`, the response is sent as Server-Sent Events (SSE) where each `data` line contains a `ChatCompletionChunk` JSON object. The stream ends with `data: [DONE]`.
# Create response (/docs/api-reference/openai-responses/createResponse)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Creates a response using the OpenAI Responses API format. Drop-in replacement for OpenAI's newer stateful-conversation surface.
When `stream: true`, the response is sent as Server-Sent Events (SSE) with the full output-item lifecycle (`response.created`, `response.output_item.added`, `response.output_text.delta`, `response.completed`, …). The cloud forwards the upstream provider's SSE stream unchanged.
# ACP gateway (/docs/guides/features/acp)
{/* TODO: rule syntax, built-in classifiers, custom predicates, response actions. */}
# AgentSkills Gateway (/docs/guides/features/agentskills)
{/* TODO: rule syntax, built-in classifiers, custom predicates, response actions. */}
# Add external keys (BYOK) (/docs/guides/features/byok)
import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
**BYOK** (bring your own key) routes your requests using your own provider account, not BitRouter's. You pay the provider directly at their list price — BitRouter takes no rev share, adds no per-token fee, and never sees plaintext keys on the cloud write path.
There are two deployment modes, each with a different key flow.
Local mode — env-var auto-detection [#local-mode--env-var-auto-detection]
Run the binary, set provider keys in the environment, you're done. No config file required.
```bash
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export GOOGLE_API_KEY=AIza...
bitrouter
```
BitRouter detects keys at startup and exposes only the providers whose keys are present. If a provider's key is missing, attempts to route to that provider return `402 Payment Required` with a structured error pointing at the missing variable.
Recognized variables [#recognized-variables]
| Provider | Preferred name | Passthrough fallback |
| ------------------------ | --------------------------------- | ---------------------------------- |
| OpenAI | `BITROUTER_OPENAI_API_KEY` | `OPENAI_API_KEY` |
| Anthropic | `BITROUTER_ANTHROPIC_API_KEY` | `ANTHROPIC_API_KEY` |
| Google | `BITROUTER_GOOGLE_API_KEY` | `GOOGLE_API_KEY`, `GEMINI_API_KEY` |
| Custom (registry-listed) | `BITROUTER__API_KEY` | — |
The `BITROUTER_*` variants take precedence over the passthrough names — useful when your shell already has `OPENAI_API_KEY` set for a different tool and you want BitRouter to use a different account.
For a custom provider registered as `id: my-provider` in the [registry](/docs/guides/overview/provider), set `BITROUTER_MY_PROVIDER_API_KEY` (uppercased, hyphens become underscores).
**Key rotation is live.** BitRouter watches the environment of its parent process; updating a key (re-export and `kill -HUP $(pgrep bitrouter)`) takes effect on the next request without restart.
Cloud mode — sealed-box encryption [#cloud-mode--sealed-box-encryption]
On `cloud.bitrouter.ai`, your provider key is encrypted **client-side** against the node's X25519 sealed-box public key before submission. The node never sees plaintext on the write path; ciphertext is decrypted in-memory at request time and never logged.
The flow:
1. **Fetch the node's public key.** [`GET /v1/byok/encryption-pubkey`](/docs/api-reference/byok/getEncryptionPubkey) returns the current X25519 public key and a `kek_id` fingerprint. Cache by fingerprint and pass it back as `If-None-Match` to short-circuit on `304 Not Modified`.
2. **Encrypt the plaintext key.** Use libsodium `crypto_box_seal` (or any sealed-box implementation) against the public key.
3. **Submit the ciphertext.** The [console](https://cloud.bitrouter.ai) does steps 1–2 in-browser when you paste a key — you never need to leave the dashboard. The same submission API is also available for scripted onboarding; see the [API reference](/docs/api-reference/byok/getEncryptionPubkey).
Encryption recipe [#encryption-recipe]
If you're scripting key submission, here's the minimum sealed-box step. The output ciphertext is what the submission endpoint expects.
```js
import sodium from 'libsodium-wrappers';
await sodium.ready;
const meta = await fetch(
'https://cloud.bitrouter.ai/v1/byok/encryption-pubkey'
).then(r => r.json());
const ciphertext = sodium.crypto_box_seal(
sodium.from_string(process.env.OPENAI_API_KEY),
sodium.from_base64(meta.public_key, sodium.base64_variants.ORIGINAL)
);
const ciphertextB64 = sodium.to_base64(ciphertext, sodium.base64_variants.ORIGINAL);
// Submit { provider: 'openai', kek_id: meta.kek_id, ciphertext: ciphertextB64 }
```
```python
import os, base64, requests
from nacl.public import PublicKey, SealedBox
meta = requests.get('https://cloud.bitrouter.ai/v1/byok/encryption-pubkey').json()
pubkey = PublicKey(base64.b64decode(meta['public_key']))
ciphertext = SealedBox(pubkey).encrypt(os.environ['OPENAI_API_KEY'].encode())
payload = {
'provider': 'openai',
'kek_id': meta['kek_id'],
'ciphertext': base64.b64encode(ciphertext).decode(),
}
# POST `payload` to the BYOK submission endpoint.
```
```bash
META=$(curl -s https://cloud.bitrouter.ai/v1/byok/encryption-pubkey)
PUBKEY=$(echo "$META" | jq -r .public_key)
KEK_ID=$(echo "$META" | jq -r .kek_id)
CIPHERTEXT=$(printf '%s' "$OPENAI_API_KEY" \
| sodium-seal --pubkey "$PUBKEY" \
| base64)
# Submit { provider: "openai", kek_id: "$KEK_ID", ciphertext: "$CIPHERTEXT" }
```
The pubkey endpoint honors `If-None-Match` for cheap caching — pin the `kek_id` from a prior response and you'll get `304 Not Modified` while the key is unchanged.
Key scope [#key-scope]
By default, keys are scoped to a [workspace](/docs/guides/features/workspaces) — every member can submit requests routed through those keys, but no one can read the ciphertext or the raw key.
For one-off overrides, attach a key to a single request via the `X-BitRouter-Key` header:
```bash
curl https://cloud.bitrouter.ai/v1/chat/completions \
-H "Authorization: Bearer $BITROUTER_TOKEN" \
-H "X-BitRouter-Key: openai=sk-..." \
-d '{...}'
```
**Per-request keys are transmitted as plaintext over TLS.** The cloud node decrypts TLS, sees the key in memory for the request, then drops it — it is never persisted. This is convenient for ephemeral scripts and CI runs, but if you submit the same key on every request, prefer the sealed-box upload path: it's both more efficient (no per-request key bytes) and harder to leak via a debug log. In local mode, the loopback hop means the plaintext header never crosses the public network.
Rotation, revocation, and audit [#rotation-revocation-and-audit]
* **Rotate** by submitting a new ciphertext for the same provider — the previous record is overwritten atomically.
* **Revoke** from the dashboard. In-flight requests using the prior key complete; new requests get `402 Payment Required`.
* **Audit** in the workspace's key history view — every submission is recorded with the submitting member, time, and `kek_id` used. Plaintext is never visible to anyone, including BitRouter operators.
If a node's `kek_id` rotates (we re-key every 90 days), already-submitted ciphertexts are re-wrapped server-side using the previous key in memory; you don't need to re-encrypt unless you explicitly choose to.
Custom providers [#custom-providers]
BYOK works for any provider listed in the [registry](/docs/guides/overview/provider) that declares `byok` in its manifest's `payment.modes`. The provider field in the encryption submission must match the registry `id` exactly. Local-mode env-var detection follows the `BITROUTER__API_KEY` convention.
# Headless CLI (/docs/guides/features/cli)
import { Callout } from 'fumadocs-ui/components/callout';
`bitrouter` is a single static binary. Past the daemon control commands (`serve`, `start`, `stop`, `status`), v1 ships two cloud-facing surfaces: `bitrouter auth …` for OAuth sign-in, and `bitrouter cloud …` for everything you can do once signed in.
Sign in to BitRouter Cloud [#sign-in-to-bitrouter-cloud]
`bitrouter auth login` runs the RFC 8628 Device Authorization Grant against the configured authorization server, prints an approval URL, and persists the resulting access + refresh tokens under `$XDG_DATA_HOME/bitrouter/account-credentials.json` (mode `0600` on Unix). The token is refreshed automatically within 60 s of expiry — you sign in once per machine.
```bash
bitrouter auth login
# Open this URL in your browser:
# https://cloud.bitrouter.ai/oauth/device?user_code=ABCD-EFGH
# Waiting for authorization (the code expires in 600s)…
```
The default authorization server is `https://api.bitrouter.ai`. Override with `--oauth-as ` (or `BITROUTER_OAUTH_AS`) for a self-hosted deployment. The default scope set covers inference plus the read/write sides of keys, usage, billing-read, policy, BYOK, and account-read — opt in to the sensitive scopes (`billing:write`, `account:write`, `clients:read`, `clients:write`) by passing `--scope " clients:write"` at login time.
Inspect the local session with `bitrouter auth whoami` — it reads the credentials file directly and never hits the network. Sign out (best-effort revoke at the AS plus delete the local file) with `bitrouter auth logout`.
After `bitrouter auth login`, the `bitrouter` provider is auto-enabled in zero-config mode — every model your account is entitled to is routable as `bitrouter:` with no further setup.
Manage your account: bitrouter cloud [#manage-your-account-bitrouter-cloud]
Every leaf accepts `--json` for raw response output; the default is a `systemctl`-style key:value block (single resource) or a small table (lists). When the server returns a 403 with `missing required scope: `, the CLI prints a copy-pasteable `bitrouter auth login --scope " "` hint.
bitrouter cloud whoami [#bitrouter-cloud-whoami]
Identity stored on this machine plus the `/v1/*` base URL the CLI will target. Offline read.
bitrouter cloud keys — API keys [#bitrouter-cloud-keys--api-keys]
```bash
bitrouter cloud keys list
bitrouter cloud keys mint --name ci --scope "policy:read usage:read"
bitrouter cloud keys revoke
```
`mint` returns the plaintext `brk_…` token exactly once — save it on first read; the server keeps only the SHA-256 hash. Requested scopes must be a subset of your effective scopes (RFC 6749 §3.3 forbids upscaling).
bitrouter cloud usage / bitrouter cloud requests [#bitrouter-cloud-usage--bitrouter-cloud-requests]
```bash
bitrouter cloud usage # last 30 days
bitrouter cloud usage --from 2026-05-01T00:00:00Z --to 2026-06-01T00:00:00Z
bitrouter cloud requests --limit 50 --offset 0
```
`usage` aggregates spend (micro-USD) and token counts. `requests` pages through the request history.
bitrouter cloud billing — balance + checkout [#bitrouter-cloud-billing--balance--checkout]
```bash
bitrouter cloud billing balance
bitrouter cloud billing checkout --amount-cents 2000 # needs billing:write
```
`checkout` returns a hosted Stripe URL. Requires the `billing:write` scope (not in the default set — re-login with `--scope`).
bitrouter cloud policy — generic policy CRUD [#bitrouter-cloud-policy--generic-policy-crud]
```bash
bitrouter cloud policy list [--kind budget|rate-limit|guardrail|preset]
bitrouter cloud policy get
bitrouter cloud policy create --name nightly-cap --kind budget --spec spec.json
bitrouter cloud policy update [--name X] [--spec spec.json]
bitrouter cloud policy delete
bitrouter cloud policy bind --principal-type api_key --principal-id
bitrouter cloud policy unbind
bitrouter cloud policy disable
bitrouter cloud policy enable
bitrouter cloud policy bindings
bitrouter cloud policy effective --principal-type api_key --principal-id
bitrouter cloud policy for-principal api_key
```
`--spec` reads a JSON file (or `-` for stdin) holding the flat inner spec body — e.g. `{"window": "day", "limit_micro_usd": 5000000}` for a budget. The `effective` and `for-principal` endpoints answer "what would happen to a request from this principal" without making an actual inference call.
bitrouter cloud budget / bitrouter cloud preset — typed sugar [#bitrouter-cloud-budget--bitrouter-cloud-preset--typed-sugar]
Flat wire shapes over budget-kind and preset-kind policies:
```bash
bitrouter cloud budget create --name nightly-cap --window day --limit-micro-usd 5000000
bitrouter cloud preset create --name engineering --guardrail guardrail.json --budget budget.json
```
These hit the same database rows as `bitrouter cloud policy create --kind budget|preset` — pick whichever shape is more convenient for the call site.
bitrouter cloud byok — BYOK provider keys [#bitrouter-cloud-byok--byok-provider-keys]
```bash
bitrouter cloud byok list
bitrouter cloud byok set --provider anthropic \
--ciphertext-b64 --kek-id --key-prefix sk-ant-
bitrouter cloud byok delete
```
Ciphertext must be sealed against the cloud's current X25519 public key before submission — the server only stores already-encrypted bytes. Fetch the current public key from `GET /v1/byok/encryption-pubkey` before sealing.
bitrouter cloud oauth-client — OAuth client registrations [#bitrouter-cloud-oauth-client--oauth-client-registrations]
```bash
bitrouter cloud oauth-client list
bitrouter cloud oauth-client register \
--name "my-agent" --type confidential \
--grant authorization_code --grant refresh_token \
--scope inference:invoke --scope policy:read \
--redirect-uri https://my-agent.example.com/cb
bitrouter cloud oauth-client update --name "renamed"
bitrouter cloud oauth-client delete
```
Requires the `clients:read` / `clients:write` scopes — not in the default set. The freshly minted `client_secret` for confidential clients is returned exactly once in the `register` response.
# Guardrails (/docs/guides/features/guardrails)
{/* TODO: rule syntax, built-in classifiers, custom predicates, response actions. */}
# MCP gateway (/docs/guides/features/mcp)
{/* TODO: rule syntax, built-in classifiers, custom predicates, response actions. */}
# Observability (/docs/guides/features/observability)
{/* TODO: traces, metrics endpoints, log shipping, CLI/TUI walkthrough. */}
# Agentic Payment (MPP & x402) (/docs/guides/features/payment)
{/* TODO: rule syntax, built-in classifiers, custom predicates, response actions. */}
# Presets (/docs/guides/features/presets)
{/* TODO: rule syntax, built-in classifiers, custom predicates, response actions. */}
# Structured Outputs (Beta) (/docs/guides/features/structured-outputs)
import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
**Beta Feature.** Structured outputs support is currently in beta. The API is stable but may receive enhancements based on user feedback. Please report any issues or suggestions on [GitHub](https://github.com/bitrouter/bitrouter/issues).
**Structured outputs** guarantee that model responses conform to your exact JSON schema. BitRouter provides a unified API that works seamlessly across all major providers — automatically translating between each provider's native format.
Quick start [#quick-start]
Define your schema once, use it everywhere. BitRouter handles the protocol translation:
```typescript
import OpenAI from 'openai';
const client = new OpenAI({
baseURL: 'https://api.bitrouter.ai/v1',
apiKey: process.env.BITROUTER_API_KEY,
});
const completion = await client.chat.completions.create({
model: 'claude-3-5-sonnet-latest',
messages: [
{ role: 'user', content: 'Extract the key facts from this article...' }
],
response_format: {
type: 'json_schema',
json_schema: {
name: 'article_facts',
strict: true,
schema: {
type: 'object',
properties: {
title: { type: 'string' },
author: { type: 'string' },
key_points: {
type: 'array',
items: { type: 'string' }
},
sentiment: {
type: 'string',
enum: ['positive', 'neutral', 'negative']
}
},
required: ['title', 'key_points', 'sentiment']
}
}
}
});
// Response is guaranteed to match your schema
const facts = JSON.parse(completion.choices[0].message.content);
```
```python
import anthropic
client = anthropic.Anthropic(
base_url="https://api.bitrouter.ai",
api_key=os.environ["BITROUTER_API_KEY"],
)
message = client.messages.create(
model="gpt-4o-2024-11-20",
messages=[
{"role": "user", "content": "Extract the key facts from this article..."}
],
output_config={
"format": {
"type": "json_schema",
"schema": {
"type": "object",
"properties": {
"title": {"type": "string"},
"author": {"type": "string"},
"key_points": {
"type": "array",
"items": {"type": "string"}
},
"sentiment": {
"type": "string",
"enum": ["positive", "neutral", "negative"]
}
},
"required": ["title", "key_points", "sentiment"]
}
}
}
)
# Response is guaranteed to match your schema
import json
facts = json.loads(message.content[0].text)
```
```bash
curl https://api.bitrouter.ai/v1/chat/completions \
-H "Authorization: Bearer $BITROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-2.0-flash-exp",
"messages": [
{"role": "user", "content": "Extract the key facts from this article..."}
],
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "article_facts",
"strict": true,
"schema": {
"type": "object",
"properties": {
"title": {"type": "string"},
"author": {"type": "string"},
"key_points": {
"type": "array",
"items": {"type": "string"}
},
"sentiment": {
"type": "string",
"enum": ["positive", "neutral", "negative"]
}
},
"required": ["title", "key_points", "sentiment"]
}
}
}
}'
```
**Protocol auto-detection.** BitRouter automatically detects which protocol you're using (OpenAI Chat, Anthropic Messages, etc.) and translates your schema to the provider's native format.
How it works [#how-it-works]
BitRouter provides a unified `response_format` field that works across all providers. When you send a request:
1. **Inbound parsing** — BitRouter detects your client protocol and extracts the schema
2. **Cross-protocol routing** — The schema is translated to the upstream provider's native format
3. **Response streaming** — Partial JSON streams back via standard `TextDelta` events
4. **Format preservation** — Responses maintain your requested protocol's shape
This means an OpenAI client can route to Anthropic, or an Anthropic client can route to Google Gemini — the translation happens automatically.
Protocol formats [#protocol-formats]
Each provider has its own native structured output format. BitRouter translates between them:
| Protocol | Native format | BitRouter accepts | Notes |
| -------------------- | ----------------------------- | ------------------------------------- | -------------------------------------------- |
| **OpenAI Chat** | `response_format.json_schema` | Same | Full support for `name`, `strict`, `schema` |
| **OpenAI Responses** | `text.format` | Same | Preserves sibling keys like `text.verbosity` |
| **Anthropic** | `output_config.format` | Also legacy `output_format` | No `name` or `strict` fields |
| **Google Gemini** | `generationConfig` | `responseMimeType` + `responseSchema` | Schema only, no name/strict |
Field mappings [#field-mappings]
When routing between protocols, BitRouter handles these transformations:
* **`name`** — Required by OpenAI, defaults to `"response"` if not provided. Dropped for Anthropic/Google.
* **`strict`** — OpenAI's strict mode flag. Dropped for providers that don't support it.
* **`schema`** — The JSON Schema itself. Passed through with provider-specific adjustments.
**No validation performed.** BitRouter is a proxy, not a validator. It passes your schema to the provider and returns their response as-is. The provider is responsible for schema enforcement.
Advanced usage [#advanced-usage]
Complex nested schemas [#complex-nested-schemas]
Structured outputs support arbitrarily complex JSON schemas with nested objects, arrays, and enums:
```typescript
const schema = {
type: 'object',
properties: {
analysis: {
type: 'object',
properties: {
entities: {
type: 'array',
items: {
type: 'object',
properties: {
name: { type: 'string' },
type: {
type: 'string',
enum: ['person', 'organization', 'location', 'event']
},
confidence: {
type: 'number',
minimum: 0,
maximum: 1
},
relationships: {
type: 'array',
items: {
type: 'object',
properties: {
target: { type: 'string' },
type: { type: 'string' }
},
required: ['target', 'type']
}
}
},
required: ['name', 'type', 'confidence']
}
},
summary: { type: 'string', maxLength: 500 },
topics: {
type: 'array',
items: { type: 'string' },
minItems: 1,
maxItems: 5
}
},
required: ['entities', 'summary', 'topics']
},
metadata: {
type: 'object',
properties: {
processed_at: { type: 'string', format: 'date-time' },
confidence_score: { type: 'number' }
},
required: ['processed_at']
}
},
required: ['analysis', 'metadata']
};
```
Streaming structured outputs [#streaming-structured-outputs]
Structured outputs work with streaming responses. Partial JSON is streamed back as text deltas:
```typescript
const stream = await client.chat.completions.create({
model: 'claude-3-5-sonnet-latest',
messages: [{ role: 'user', content: 'Analyze this document...' }],
response_format: {
type: 'json_schema',
json_schema: { name: 'analysis', schema: schema }
},
stream: true
});
let buffer = '';
for await (const chunk of stream) {
const delta = chunk.choices[0]?.delta?.content;
if (delta) {
buffer += delta;
// Partial JSON accumulates: {"analysis":{"entities":[{"name":"Acme Corp"...
}
}
const result = JSON.parse(buffer);
```
Provider-specific considerations [#provider-specific-considerations]
OpenAI [#openai]
* Requires a `name` field (BitRouter supplies `"response"` as default)
* Supports `strict: true` for stricter schema enforcement
* Works with GPT-4o models (Nov 2024+) and newer
Anthropic [#anthropic]
* Native support via `output_config.format` (no beta headers needed)
* Doesn't support `name` or `strict` fields (BitRouter drops them)
* Works with Claude 3.5 Sonnet and newer
Google Gemini [#google-gemini]
* Uses `generationConfig.responseMimeType: "application/json"`
* Schema goes in `generationConfig.responseSchema`
* Works with Gemini 1.5 Pro and Flash models
Custom providers [#custom-providers]
Any provider registered in BitRouter's [provider registry](/docs/guides/overview/provider) can support structured outputs through our unified schema format.
Limitations [#limitations]
Model requirements [#model-requirements]
All leading agentic LLMs available on BitRouter Cloud support structured outputs, including:
* **OpenAI**: GPT-4o, GPT-4o-mini, o1, o1-mini, o3-mini
* **Anthropic**: Claude 3.5 Sonnet, Claude 3.5 Haiku, Claude 3 Opus
* **Google**: Gemini 2.0 Flash, Gemini 1.5 Pro, Gemini 1.5 Flash
* **DeepSeek**: DeepSeek V3, DeepSeek R1
* **Meta**: Llama 3.3 70B, Llama 3.1 405B
* **Others**: Most modern models support JSON schemas
Schema constraints [#schema-constraints]
* Maximum schema size varies by provider (typically 10-50KB)
* Some providers limit nesting depth (usually 10-20 levels)
* Certain JSON Schema features may not be supported (e.g., `$ref`, `patternProperties`)
Not supported [#not-supported]
* **Response validation** — BitRouter doesn't validate responses against schemas
* **Schema conversion** — Input must be valid JSON Schema, no TypeScript/Zod/etc.
* **Legacy JSON mode** — Use `response_format: { type: "json_object" }` separately
**Error handling.** If a model doesn't support structured outputs, you'll receive a `400 Bad Request` with details about the incompatibility. If the schema is invalid, the provider will return their specific error message.
Migration guide [#migration-guide]
If you're currently using provider-specific structured output APIs, here's how to migrate:
From OpenAI [#from-openai]
No changes needed — BitRouter accepts the same format:
```typescript
// Works as-is
response_format: {
type: 'json_schema',
json_schema: { name: 'my_schema', strict: true, schema: {...} }
}
```
From Anthropic [#from-anthropic]
Update to use the unified format:
```python
# Before (Anthropic-specific)
output_config={"format": {"type": "json_schema", "schema": {...}}}
# After (BitRouter unified)
response_format={
"type": "json_schema",
"json_schema": {"schema": {...}} # name and strict are optional
}
```
From Google Gemini [#from-google-gemini]
Switch from split fields to unified format:
```javascript
// Before (Gemini-specific)
generationConfig: {
responseMimeType: 'application/json',
responseSchema: {...}
}
// After (BitRouter unified)
response_format: {
type: 'json_schema',
json_schema: { schema: {...} }
}
```
See also [#see-also]
* [Model discovery](/docs/api-reference/discovery/listModels) — Check which models support structured outputs
* [Provider selection](/docs/guides/routing/provider-selection) — Route to providers with structured output support
* [API Reference](/docs/api-reference) — Complete API documentation
# Workspaces (/docs/guides/features/workspaces)
import { Callout } from 'fumadocs-ui/components/callout';
A **workspace** is BitRouter's isolation boundary. API keys, policies, and usage data are all scoped to a single workspace. You can own any number of workspaces — one per project, environment, or agent deployment.
Credential model: user-scoped vs. workspace-scoped [#credential-model-user-scoped-vs-workspace-scoped]
Every credential is either **user-scoped** or **workspace-scoped**. This is set at issuance and cannot be changed.
| | User-scoped | Workspace-scoped |
| ----------------------------------------------------- | --------------------------------------- | ---------------------------------------------- |
| **Carried by** | Console web session (your browser) | CLI sessions, API keys (`brk_`), device tokens |
| **Reach** | All your workspaces + account-level ops | Exactly one workspace |
| **Create / delete workspaces** | Yes | No |
| **Manage billing** | Yes | Read-only |
| **Manage keys, policies, usage within the workspace** | Yes | Yes |
| **Invoke inference** | Playground only | Yes |
The Console web session is the **only** user-scoped credential. No long-lived root credential spans workspaces — that scope is intentionally unavailable to CLI sessions and `brk_` keys.
Signing in to a workspace [#signing-in-to-a-workspace]
`bitrouter auth login` runs the OAuth device flow. The browser approval page asks you to pick which workspace to grant the CLI access to. The resulting credential is baked to that workspace — all subsequent `bitrouter cloud` commands target it implicitly, with no `--workspace` flag required anywhere.
```bash
bitrouter auth login
# Open this URL in your browser to pick a workspace:
# https://cloud.bitrouter.ai/oauth/device?user_code=ABCD-EFGH
```
To see which workspace your current session is bound to:
```bash
bitrouter cloud namespace current # offline — reads local credential
bitrouter auth whoami # also prints the bound namespace
```
To switch to a different workspace, re-run `bitrouter auth login` and pick a different workspace in the browser. The old credential is replaced.
```bash
bitrouter cloud namespace list # all your workspaces; active one marked
```
```
ns_01jxyz… default (active)
ns_01jabc… production
ns_01jdef… staging
```
See the [CLI reference](/docs/guides/features/cli) for the full `bitrouter cloud` surface.
Full agent control inside the boundary [#full-agent-control-inside-the-boundary]
Once signed in, a CLI session (or a `brk_` API key minted from it) has full autonomy within its workspace:
**Keys** — create, list, and revoke API keys scoped to this workspace. Any key minted here is also workspace-baked and inherits the same boundary.
```bash
bitrouter cloud keys mint --name my-agent \
--scope "inference:invoke keys:read policy:read usage:read"
bitrouter cloud keys list
bitrouter cloud keys revoke
```
**Policies** — read and write guardrail, rate-limit, and preset policy bindings.
```bash
bitrouter cloud policy list
bitrouter cloud policy bind --principal-type api_key --principal-id
bitrouter cloud budget create --name daily-cap --window day --limit-micro-usd 5000000
```
**Usage** — read per-workspace request history and spend.
```bash
bitrouter cloud usage
bitrouter cloud requests --limit 50
```
An agent or CI job using a workspace-baked credential has no ability to reach other workspaces, manage billing, or mint a wider credential. The blast radius is bounded to the workspace.
`bitrouter cloud keys mint` is the recommended way for an agent to provision sub-keys for its own tools. The minted key is workspace-baked to the same workspace as the caller and cannot upscale its scopes beyond the caller's.
Managing workspaces [#managing-workspaces]
A default workspace is provisioned automatically on first login. Additional workspaces are created and deleted from the Console — workspace lifecycle is a control-plane operation and requires a user-scoped credential (your web session).
The CLI supports listing only:
```bash
bitrouter cloud namespace list # all workspaces you own
bitrouter cloud namespace current # the one this session is bound to (offline)
```
You cannot delete your last workspace. BitRouter requires at least one workspace per account.
Usage reporting [#usage-reporting]
Per-workspace usage is attributed at settlement time and available from both the CLI and the Console:
```bash
bitrouter cloud usage # last 30 days
bitrouter cloud usage --from 2026-05-01T00:00:00Z --to 2026-06-01T00:00:00Z
bitrouter cloud requests --limit 25 # paginated request log
```
For account-wide spend, see the [Billing](/docs/guides/features/payment) guide. Workspace-level spend caps are on the roadmap.
# Comparison (/docs/guides/overview/comparison)
BitRouter is the only **smart router and open marketplace built specifically for agents** — open (Apache 2.0, locally deployable, permissionless registration and usage), intelligent (multi-provider routing, programmable fallbacks, runtime guardrails, sub-10ms overhead), and agent-native (KYA identity, autonomous x402/MPP payments, MCP/ACP gateway, reliability primitives for long-running loops).
Most existing tools fall into one of three categories. None covers all three properties at once.
vs Cloud SaaS routers (OpenRouter and similar) [#vs-cloud-saas-routers-openrouter-and-similar]
Cloud SaaS routers — like **OpenRouter** — route requests across hundreds of models behind a hosted endpoint, optimized for human-facing apps.
* **Self-hostable** — Cloud SaaS routers are closed-source and cloud-only. BitRouter is Apache 2.0; run it anywhere as a single binary.
* **Permissionless access** — These services require account creation and credit card or crypto top-up. BitRouter's hosted option uses x402/Solana — no KYC, no geo-restrictions, agents pay per request.
* **Agent-first features** — Cloud SaaS routers have no agent firewall, no MCP/ACP gateway, and no skills registry. BitRouter is built around them.
* **Lower latency** — Sub-10ms routing overhead vs \~25–40ms typical for hosted routers.
vs Self-hosted proxies (LiteLLM and similar) [#vs-self-hosted-proxies-litellm-and-similar]
Self-hosted proxies — like **LiteLLM** — are open-source SDKs and Python proxies popular for backend services. They're BYOK and infra-heavy.
* **Zero-ops** — These proxies typically require Postgres, Redis, and Docker/K8s in production. BitRouter is one binary, no dependencies.
* **Performance** — Python-based proxies hit the GIL at scale; tail latency degrades under concurrent load. BitRouter's Rust async runtime keeps latency flat.
* **Payments** — Self-hosted proxies are BYOK only and have no payment handling. BitRouter's hosted option supports autonomous agent payments.
* **Agent runtime** — These proxies have no in-line content safety, no KYA identity, no skills registry. BitRouter does.
vs Generic API gateways (Portkey, Kong AI, AWS Bedrock Gateway, etc.) [#vs-generic-api-gateways-portkey-kong-ai-aws-bedrock-gateway-etc]
Generic API gateways treat LLMs as just another upstream API. They typically offer logging, caching, rate limiting, provider failover, BYOK billing, and dashboards.
They don't offer:
* Agent identity or runtime model discovery
* Autonomous payment protocols (x402/MPP)
* MCP or ACP gateway functionality
* A skills registry for agent capabilities
* Sub-10ms native binary deployment
These gateways fit traditional API operations. BitRouter exists because **autonomous agents need a different surface** — runtime model selection, payment delegation, in-line safety, and a single open standard for tool and sub-agent discovery.
# Introduction (/docs/guides/overview)
What is BitRouter? [#what-is-bitrouter]
BitRouter is an **agent-native LLM router that optimizes your agent with every run**. It's a single local binary that gives any agent one endpoint to discover, route to, and pay for LLMs and tools across providers — with **zero harness changes**. Point your runtime at it and every model call becomes reliable, traceable, secure, and cost-effective.
It runs anywhere your agent runs, with no dependencies to install, and is operated as a permissionless network where any provider can register and any agent can connect. Open-sourced under Apache 2.0; Cloud is opt-in.
Why agents run on BitRouter [#why-agents-run-on-bitrouter]
Four mechanisms, built into the router — not bolted on per agent.
Reliability — one provider fails, your agent run doesn't [#reliability--one-provider-fails-your-agent-run-doesnt]
BitRouter reroutes across providers mid-run, transparently — your agent never sees the failed call. Automatic retries with exponential backoff, model and provider fallbacks, connection reuse, and request-level idempotency keep long agent loops alive through outages and `429`s. Failed requests aren't billed. See [Model Fallback](/docs/guides/routing/model-fallback) and [Provider Selection](/docs/guides/routing/provider-selection).
Observability — trace every hop, not just every request [#observability--trace-every-hop-not-just-every-request]
Full call-chain visibility: every agent, every model, every step, with cost attributed **per run** rather than per month. A real-time CLI + TUI monitors sessions, requests, latency, and spend, and structured logs feed downstream pipelines. See [Observability](/docs/guides/features/observability).
Security — guardrails for every agent, configured once [#security--guardrails-for-every-agent-configured-once]
Prompt-injection detection, PII and output filtering, and rate limits — enforced at the router, once, for every agent, with no application-level changes. Combined with per-agent [KYA](/docs/guides/features/payment) identity, an autonomous agent holding your keys stops being an unsupervised attack surface. See [Guardrails](/docs/guides/features/guardrails).
Efficiency — not every call needs your strongest model [#efficiency--not-every-call-needs-your-strongest-model]
Most calls in a run are trivial — a lookup, a format, a yes/no. BitRouter matches each call to the right model by task complexity with price-aware routing, so you stop billing simple calls at frontier prices. The savings compound across every run.
The foundation [#the-foundation]
* **Universal LLM API** — One binary, three protocol surfaces: OpenAI Chat Completions + Responses, Anthropic Messages, and Google Generative AI. Talk to any LLM through your preferred protocol, and route cross-protocol (OpenAI ↔ Anthropic).
* **Free BYOK** — Bring your own provider keys at zero cost. BitRouter auto-detects keys from environment variables — no config file required.
* **MCP & ACP gateway** — Proxy [MCP](https://modelcontextprotocol.io) servers so agents can discover and call tools across hosts. [ACP](https://github.com/zed-industries/acp) support for agent identity, discovery, and task dispatch.
* **Agentic auth & payment** — KYA (Know-Your-Agent) identity and x402/MPP pay-per-use on the hosted service. Agents authenticate and pay autonomously — no credit cards, no prepaid credits, no invoices.
* **Open ecosystem** — Permissionless [provider registration](/docs/guides/overview/provider). Any provider exposing an OpenAI- or Anthropic-compatible endpoint can join the network and be discovered by agents on it.
How BitRouter compares [#how-bitrouter-compares]
BitRouter, LiteLLM, and OpenRouter all route LLM traffic, but BitRouter is the only one that is **open-source and self-hostable, agent-native, and built on a permissionless provider marketplace** — with automatic mid-run failover and sub-10ms routing overhead. See the full [Comparison](/docs/guides/overview/comparison) against OpenRouter, LiteLLM, and other API gateways.
Why we're building this [#why-were-building-this]
Today's LLM agents lose hours of work to a single provider outage, rewrite integration code every time they swap models, ship risky outputs with no consistent way to redact or block them, and operate in the dark because each provider only shows its own slice. BitRouter survives outages with automatic fallback, lets agents swap models without code changes, redacts or blocks risky content at the proxy, and shows every call, cost, and error in one feed. The longer goal is an open, permissionless intelligence layer where agents discover, route to, and pay for their own resources — owned by the agents and operators using it, not a gateway company in the middle.
Agent Runtimes [#agent-runtimes]
BitRouter is a drop-in proxy for any runtime that supports a custom OpenAI or Anthropic base URL — point it at `http://localhost:8787` and you're done.
Setup recipes for OpenClaw, Hermes Agent, Claude Code, and more live in the [Cookbook](/docs/cookbook).
AI Resources [#ai-resources]
Material to feed into your agent or LLM context:
* **[`llms.txt`](https://bitrouter.ai/llms.txt)** — Curated BitRouter documentation index in the [llms.txt](https://llmstxt.org) format.
* **[`llms-full.txt`](https://bitrouter.ai/api/docs/llms-full.txt)** — Complete documentation as plain text for full-context ingestion.
* **[Agent Skills](https://github.com/bitrouter/agent-skills)** — Drop-in skills that teach an agent (Claude Code, Cursor, Copilot, Codex, etc.) how to install and use BitRouter. Install with `npx skills add BitRouterAI/agent-skills`.
* **[BitRouter CLI](https://github.com/bitrouter/bitrouter)** — `cargo install bitrouter` to install. Runs the proxy, an interactive setup wizard, and the TUI dashboard.
* **[Comparison](/docs/guides/overview/comparison)** — How BitRouter differs from OpenRouter, LiteLLM, and other API gateways.
# For Providers (/docs/guides/overview/provider)
import { Callout } from 'fumadocs-ui/components/callout';
The BitRouter Registry is **experimental**. Pull requests are reviewed and merged case-by-case during this phase, and we reserve the right to reject or delist providers — see [Terms of Use](#terms-of-use) below. The end goal is fully permissionless onboarding; the current process exists to keep the network healthy while we get there.
The BitRouter Registry [#the-bitrouter-registry]
BitRouter is designed as an **open marketplace** for inference. Anyone running an OpenAI- or Anthropic-compatible inference endpoint can apply to register their models — no commercial agreement, no sales cycle, no business form.
Provider listings live in a public, open-source repo:
> **[github.com/bitrouter/provider-registry](https://github.com/bitrouter/provider-registry)**
You apply by opening a pull request that adds your provider manifest. Once merged, BitRouter and any agent on the network can discover your models, route to them, and (optionally) pay you per request via x402/MPP.
How Registration Works [#how-registration-works]
1. Fork [provider-registry](https://github.com/bitrouter/provider-registry).
2. Add a manifest at `providers/.yaml` describing your endpoint and model catalog.
3. Open a PR. CI runs schema validation and basic reachability checks against your endpoint.
4. A maintainer reviews the PR. While we aim to merge openly, PRs are evaluated case-by-case during the experimental phase.
5. On merge, your models become discoverable across the BitRouter network and the hosted bitrouter.ai marketplace.
**Registry inclusion ≠ guaranteed traffic.** Being listed in the registry makes your models discoverable, but does not guarantee any volume of inference traffic. BitRouter runs an independent **router** that continuously monitors, scores, and ranks providers — see [Reliability & Routing](#reliability--routing) below. Traffic flows to providers that score well; weaker signals lead to deprioritization, regardless of registry status.
Provider Manifest [#provider-manifest]
A manifest declares your endpoint metadata, payment modes, and the model-catalog URL that BitRouter polls.
```yaml
id: example-provider
name: Example AI
endpoint: https://api.example.ai/v1
protocol: openai # openai | anthropic
models_url: https://api.example.ai/v1/models
payment:
modes: [byok, x402]
x402_address: "0x..." # optional, for hosted agent payments
homepage: https://example.ai
support: https://example.ai/support
```
Models Endpoint [#models-endpoint]
BitRouter periodically polls your `models_url` and expects a list of all available models in the following schema.
```json
{
"data": [
{
"id": "example/sonnet-1",
"name": "Example: Sonnet 1",
"created": 1704067200,
"input_modalities": ["text", "image"],
"output_modalities": ["text"],
"context_length": 1000000,
"max_output_length": 128000,
"quantization": "fp8",
"pricing": {
"prompt": "0.000003",
"completion": "0.000015",
"image": "0",
"request": "0",
"input_cache_read": "0"
},
"supported_sampling_parameters": ["temperature", "top_p", "stop"],
"supported_features": ["tools", "json_mode", "structured_outputs", "reasoning"],
"is_ready": true
}
]
}
```
Key fields:
* **`id`** — exact identifier BitRouter passes to your endpoint when routing requests.
* **`pricing`** — string-encoded USD per token to avoid floating-point drift. `image` and `request` are per unit.
* **`is_ready`** — set `false` to stage a model without making it live (useful for embargoed launches). Defaults to `true`.
Valid `quantization`: `int4`, `int8`, `fp4`, `fp6`, `fp8`, `fp16`, `bf16`, `fp32`.
Valid `supported_features`: `tools`, `json_mode`, `structured_outputs`, `logprobs`, `web_search`, `reasoning`.
Valid `supported_sampling_parameters`: `temperature`, `top_p`, `top_k`, `min_p`, `top_a`, `frequency_penalty`, `presence_penalty`, `repetition_penalty`, `stop`, `seed`, `max_tokens`, `logit_bias`.
Tiered Pricing [#tiered-pricing]
For long-context tiered pricing, supply `pricing` as an array. The first entry is the base tier; subsequent entries apply once input-token count reaches `min_context`.
```json
{
"pricing": [
{ "prompt": "0.000002", "completion": "0.000012" },
{ "prompt": "0.000004", "completion": "0.000018", "min_context": 200000 }
]
}
```
Deprecation [#deprecation]
Set `deprecation_date` (ISO 8601, `YYYY-MM-DD`) on a model scheduled for retirement. BitRouter surfaces deprecation warnings to consumers and may auto-hide the model after that date.
Reliability & Routing [#reliability--routing]
The registry tells BitRouter what models *exist* on your endpoint. The **router** decides how much traffic to send. They are separate systems.
The router continuously monitors uptime and performance per endpoint, then scores and ranks providers for every request. Scores update in real time — a provider that degrades will see traffic shift away within minutes.
**Uptime** — successful requests ÷ total requests, excluding user-input errors.
* Counts against uptime: `401`, `402`, `404`, `5xx`, mid-stream errors, success-with-error-finish-reason.
* Doesn't count: `400`, `413`, `429`, `403` (tracked separately).
**Performance** — TTFT (time to first token) and throughput (output tokens ÷ total generation time, including queue + fetch + streaming). Both are public on each model page.
To score well and receive traffic:
* Return early `429`s when overloaded — don't queue.
* Stream tokens as soon as they're available.
* Send SSE keep-alive comments during long pre-token work (e.g. reasoning) so the router doesn't time out and fall back.
Providers with consistently poor scores will be deprioritized. Providers that abuse the network or violate the [Terms of Use](#terms-of-use) below will be delisted entirely.
Payments [#payments]
Providers can accept payment in three modes, declared in the manifest:
* **`byok`** — consumers bring their own API key for your service. BitRouter doesn't intermediate payment.
* **`x402`** — accept agent-native x402/MPP payments per request. BitRouter routes payment receipts to the address in your manifest.
* **`invoice`** — opt into invoiced billing for aggregated hosted-mode traffic.
Most new providers start with `byok` plus `x402`, then add `invoice` once volume warrants it.
Updating Your Listing [#updating-your-listing]
Manifest updates (new models, pricing changes, endpoint moves) are PRs to the registry. Pricing changes take effect on merge. To take a model offline, set `is_ready: false` in the next models-endpoint poll or open a PR removing it.
Terms of Use [#terms-of-use]
By registering as a provider you agree to the following. Violations result in delisting from the registry and the hosted marketplace.
* **No harmful content** — endpoints must not be used to generate or knowingly facilitate CSAM, weapons-of-mass-destruction uplift, targeted harassment, or other content prohibited by applicable law.
* **No malicious behavior** — no credential harvesting, prompt-injection attacks against agents, response tampering, or covert data exfiltration.
* **Honest metadata** — the manifest and models endpoint must accurately reflect what your endpoint actually serves: pricing, context length, capabilities, modalities. Fraudulent metadata is grounds for immediate delisting.
* **Reasonable availability** — providers that consistently fail health checks or fail to respond to maintainer outreach may be delisted.
* **Lawful operation** — providers must comply with the laws of jurisdictions in which they operate, including export controls and sanctions where applicable.
We reserve the right to reject or delist any provider at our discretion during the experimental phase. As the network and tooling mature, we will narrow this discretion toward objective, automated criteria.
Get Help [#get-help]
* Open an issue on [provider-registry](https://github.com/bitrouter/provider-registry/issues).
* Join the [Discord](https://discord.gg/G3zVrZDa5C).
# Quick Start (/docs/guides/overview/quickstart)
import { Callout } from 'fumadocs-ui/components/callout';
import { Cards, Card } from 'fumadocs-ui/components/card';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
This guide gets BitRouter routing for your agent in under a minute. There are two deployment modes — and two ways to onboard either mode:
* **BitRouter Cloud (default).** Hosted endpoint at `cloud.bitrouter.ai`. No keys to manage; agent-native x402/MPP pay-per-use, or BYOK on top.
* **Local proxy.** Single binary on your machine, BYOK with your own provider keys. Zero infrastructure dependencies.
Both modes onboard through **Agent Skills** (let your agent install and configure itself) or the **BitRouter CLI / TUI** (interactive wizard). Both default to Cloud; switch to local with a single keypress.
Agent Skills [#agent-skills]
For agent runtimes that support skills (Claude Code, Cursor, Codex, Copilot, etc.). Install once:
```bash
npx skills add BitRouterAI/agent-skills
```
Then ask your agent: *"Set up BitRouter for me."* — the agent runs the wizard, picks Cloud by default, and verifies the connection autonomously.
BitRouter CLI [#bitrouter-cli]
For terminal-first setup. Install the binary:
```bash
curl -fsSL https://bitrouter.ai/install.sh | sh
```
```bash
npm install -g bitrouter
```
```bash
brew install bitrouter/tap/bitrouter
```
```bash
cargo install bitrouter
```
Launch the TUI wizard:
```bash
bitrouter
```
The wizard asks **Cloud or local?** (default Cloud), prompts for keys if you choose local, then starts the proxy at `http://localhost:8787`.
Verify with a request:
```bash
curl http://localhost:8787/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-4o",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
Point any OpenAI-compatible runtime at `http://localhost:8787/v1` to route through BitRouter.
Next Steps [#next-steps]
Recipes for connecting specific agent runtimes — Claude Code, OpenClaw, Codex CLI, OpenCode, Kilo Code, and more — live in the Cookbook.
# Model Fallback (/docs/guides/routing/model-fallback)
import { Callout } from 'fumadocs-ui/components/callout';
LLM endpoints fail. Rate limits, model outages, context-overflow errors, and content filters all surface as request errors that would otherwise stall an agent loop. **Model fallback** lets you pass a ranked list of models in a single request — BitRouter walks the list until one succeeds, then returns that response.
This is a body-level extension to the OpenAI, Anthropic, and Google protocol surfaces. No SDK required — set one field.
Quick example [#quick-example]
```bash
curl http://localhost:8787/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-4o",
"models": [
"openai/gpt-4o",
"anthropic/claude-sonnet-4-6",
"google/gemini-2.5-pro"
],
"messages": [{"role": "user", "content": "Summarize the Iliad in one sentence."}]
}'
```
The `model` field stays the primary for billing and routing semantics. The `models` array overrides it as an ordered preference list — first one that returns successfully wins.
**You can omit `model` entirely when `models` is set.** If both are present, the first entry of `models` is the primary and `model` is ignored. We recommend always passing `model` so error logs in your app stay readable.
What triggers a fallback [#what-triggers-a-fallback]
BitRouter falls through to the next model on errors that are **upstream-side and likely transient**, and surfaces 4xx errors caused by your request directly to the caller.
| Outcome | Signal | Behavior |
| -------------------------------------- | --------------------------------- | ------------------------------------------ |
| Rate limited | `429` | Fall through |
| Server error | `5xx` | Fall through |
| Timeout / connection drop | `408`, network error | Fall through |
| Context window exceeded | provider-specific code | Fall through |
| Content filter / refusal | provider-specific code | Fall through |
| Mid-stream failure (no tokens emitted) | stream aborted before first token | Fall through |
| Mid-stream failure (after first token) | stream aborted mid-response | **Surfaced** — partial output already sent |
| Authentication error | `401` | Surfaced |
| Forbidden / quota exhausted | `402`, `403` | Surfaced |
| Validation / bad request | `400`, `422` | Surfaced |
| Explicit cancel | client disconnect | Surfaced |
Fallback is single-pass. BitRouter attempts each model at most once per request, in order. There is no exponential backoff between attempts — the assumption is that you'd rather retry on a different model immediately than wait on a failing one.
**Fallback runs per request, not per token.** If a stream succeeds on model A and disconnects after token 50, BitRouter does not silently restart on model B — that would emit a discontinuous response. Wrap fallback at the request boundary; checkpoint and resume in your agent for stream-level resilience.
Inspecting which model answered [#inspecting-which-model-answered]
Three breadcrumbs:
* **Response body `model` field** — set to the model that actually generated the response, not the one you requested first. (OpenAI convention.)
* **Response header `bitrouter-served-by`** — `/`, e.g. `anthropic-direct/anthropic/claude-sonnet-4-6`.
* **Response header `bitrouter-fallback-trace`** — comma-separated list of attempts and outcomes, e.g. `openai/gpt-4o:rate_limit,anthropic/claude-sonnet-4-6:served`. Only emitted when at least one fallback fired.
Cost and latency tradeoffs [#cost-and-latency-tradeoffs]
Each fallback attempt is a fresh upstream request. Practical advice:
* Lowest expected cost: order by **cheapest first**, accept higher tail latency under load.
* Lowest expected latency: order by **most reliable first**, accept higher per-token cost.
* For long-running agent loops: bias toward reliability. The cost of a stalled loop is much higher than the marginal cost difference between two frontier models.
For declarative cost or latency optimization across providers of a single model, see [Provider Selection](/docs/guides/routing/provider-selection). Fallback and provider selection compose: BitRouter picks the best provider for each model in your `models` array, falling through to the next model only after the chosen provider for the current one has exhausted its retry budget.
Anthropic and Google surfaces [#anthropic-and-google-surfaces]
The `models` field works identically on `/v1/messages` (Anthropic Messages) and `/v1beta/models/{model}:generateContent` (Google Generative AI). On Anthropic, the field is read alongside the existing `model` field; on Google, BitRouter accepts it as an extension to the request body — the upstream `:generateContent` path is rewritten per attempt.
Limits [#limits]
* Maximum 8 entries in `models`.
* Each model ID must resolve to a registered model in the [registry](/docs/guides/overview/provider). Unknown IDs return `400` before any upstream attempt.
* Streaming is supported. The first model that begins emitting tokens wins; later models are not attempted even if the stream fails after the first token.
# Model Variants (/docs/guides/routing/model-variants)
# Provider Selection (/docs/guides/routing/provider-selection)
import { Callout } from 'fumadocs-ui/components/callout';
Most models on BitRouter are served by more than one provider. When you request `openai/gpt-4o`, BitRouter has to pick which registered endpoint to send the request to. By default it uses a balanced score; with the `provider.sort` field, you choose the policy explicitly.
There are three policies. Pick whichever matters most for the request.
The three policies [#the-three-policies]
| Policy | Optimizes for | Tie-break |
| ------------ | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `price` | Lowest cost per request, computed against your prompt and expected completion tokens at current upstream pricing. | Higher uptime → lower error rate → provider ID. |
| `latency` | Lowest observed p50 TTFT (time to first token) over the rolling 1-hour window. | Higher throughput → higher uptime → provider ID. |
| `throughput` | Highest observed output tokens per second over the rolling 1-hour window. | Lower TTFT → higher uptime → provider ID. |
Telemetry is refreshed every minute. The same data is visible on each model's page in the registry.
Quick example [#quick-example]
```bash
curl http://localhost:8787/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-4o",
"provider": { "sort": "latency" },
"messages": [{"role": "user", "content": "Translate to French: Hello."}]
}'
```
The same `provider.sort` field works on `/v1/messages` (Anthropic) and `/v1beta/models/{model}:generateContent` (Google).
BYOK providers come first [#byok-providers-come-first]
If you've [added an external key](/docs/guides/features/byok) for a provider, BitRouter prefers that provider for any model it can serve — ahead of every non-BYOK provider, regardless of `provider.sort`. Your BYOK key bills against your own account at upstream list price with no rev share, and you opted into that provider explicitly; honoring that opt-in by default is the only choice that doesn't surprise you later.
Within the BYOK-eligible set, the `provider.sort` policy still applies. So `provider.sort: "latency"` plus BYOK keys for OpenAI and Anthropic ranks those two by TTFT first, and falls back to non-BYOK providers (also ranked by latency) only if both BYOK paths fail.
In **local mode** this section is a no-op — every provider is BYOK by definition.
Default behavior [#default-behavior]
When `provider` is not set, BitRouter ranks by a **balanced score** — a weighted combination of price, latency, throughput, and uptime, with low-uptime providers filtered out. This is the right default for most agents; specify a policy only when one axis dominates.
**The default is not stable across versions.** The weights in the balanced score are tuned over time as we learn from real traffic. If you need a fixed, reproducible policy — for cost reporting, SLO tracking, or A/B tests — set `provider.sort` explicitly.
How selection composes with fallback [#how-selection-composes-with-fallback]
[Model fallback](/docs/guides/routing/model-fallback) and provider selection are independent layers:
1. For each model in your `models` list (or the single `model` if no fallback), BitRouter applies your `provider.sort` policy to pick the best provider.
2. If the chosen provider fails in a way that doesn't surface to the caller (rate limit, 5xx), BitRouter retries on the **next-ranked provider of the same model** before falling through to the next model in the list.
3. The same `provider.sort` policy applies to every model in the fallback list — you cannot specify a different policy per model.
Concretely: `models: ["openai/gpt-4o", "anthropic/claude-sonnet-4-6"]` with `provider.sort: "price"` evaluates the cheapest provider of GPT-4o first, then the cheapest provider of Sonnet, then surfaces the error.
When metrics are tied [#when-metrics-are-tied]
If two providers price the same prompt identically, the higher-uptime one wins. If uptime is also tied, the lower-error-rate one wins. If everything is tied, BitRouter sorts by provider ID lexicographically — deterministic and audit-friendly, but it does not "load balance." If even spend distribution across tied providers matters for your workload, post a use case to [Discord](https://discord.gg/G3zVrZDa5C); we'll add a `provider.balance` knob if there's demand.
What's not here [#whats-not-here]
OpenRouter exposes a much larger surface — `provider.order`, `provider.allow_fallbacks`, `provider.require_parameters`, `provider.data_collection`, `provider.ignore`, `provider.quantizations`, and more. We are deliberately keeping this to one knob with three values until usage tells us otherwise. Two equivalent expressions if you're migrating:
* **Pin to a specific provider** — use the provider-prefixed model ID, e.g. `model: "anthropic-direct/anthropic/claude-sonnet-4-6"`.
* **Exclude a provider** — omit it from your workspace's registry allowlist, not the request body.
If a missing knob is blocking a real workload, file an issue on [bitrouter](https://github.com/bitrouter/bitrouter).
# Router Variants (/docs/guides/routing/router-variants)
# 食谱 (/zh/docs/cookbook)
浏览[集成](/docs/cookbook/integration/claude-code)接入各类 AI 编程 Agent，或[迁移](/docs/cookbook/migration/litellm)从 LiteLLM 或 OpenRouter 切换过来。
# API Reference (/zh/docs/api-reference)
import { Callout } from 'fumadocs-ui/components/callout';
The BitRouter API is in **early beta**. Endpoints, request/response formats, and behavior may change without notice.
Base URL: `https://api.bitrouter.ai`. Most endpoints live under `/v1`. Routing endpoints accept either `x-api-key: ` or `Authorization: Bearer `. Pick an endpoint group from the sidebar.
# 文档 (/zh/docs/guides)
从[概览](/docs/guides/overview)开始快速了解，然后进入[模型与路由](/docs/guides/routing/model-fallback)或[功能](/docs/guides/features/workspaces)查看细节。
# Claude Code (/zh/docs/cookbook/integration/claude-code)
Claude Code Integration [#claude-code-integration]
Quick Start [#quick-start]
```bash
# 1. Start BitRouter
bitrouter serve
# 2. Configure Claude Code
export ANTHROPIC_API_BASE=http://localhost:8787
# 3. Launch Claude Code
claude
```
What You Get [#what-you-get]
* ✅ **Multi-provider access** - Route to OpenAI, Google, DeepSeek beyond Anthropic
* ✅ **Cost optimization** - Automatically use cheaper models for simple tasks
* ✅ **Fallback providers** - Never get blocked by API outages
* ✅ **Session tracking** - Monitor all Claude Code sessions in one place
* ✅ **MCP gateway** - Access all MCP tools through BitRouter
Installation [#installation]
Prerequisites [#prerequisites]
```bash
# Install Claude Code (choose one)
winget install Anthropic.ClaudeCode # Windows
code --install-extension claude-code # VS Code
```
Connect to BitRouter [#connect-to-bitrouter]
Choose your integration method:
Option 1: Simple API Proxy [#option-1-simple-api-proxy]
```bash
export ANTHROPIC_API_BASE=http://localhost:8787
claude
```
Option 2: ACP Protocol (Advanced) [#option-2-acp-protocol-advanced]
```bash
# Terminal 1: Start BitRouter with ACP
bitrouter acp
# Terminal 2: Connect Claude Code
claude --api-base http://localhost:8787 --protocol acp
```
Option 3: Skills Integration [#option-3-skills-integration]
```bash
# Auto-configure with skills
npx skills add BitRouterAI/claude-code-integration
claude
```
Essential Configuration [#essential-configuration]
Smart Task Routing [#smart-task-routing]
```yaml
# ~/.bitrouter/config.yaml
routes:
# Heavy refactoring → Most capable model
- match: "claude-code/refactor/*"
provider: anthropic
model: claude-3-5-sonnet-latest
# Test generation → Specialized model
- match: "claude-code/test/*"
provider: deepseek
model: deepseek-coder
# Quick fixes → Fast & cheap model
- match: "claude-code/quick/*"
provider: openai
model: gpt-4o-mini
# Documentation → Optimized model
- match: "claude-code/docs/*"
provider: anthropic
model: claude-3-5-haiku-latest
```
High Availability Setup [#high-availability-setup]
```yaml
routes:
- match: "claude-code/*"
provider: anthropic
model: claude-3-5-sonnet-latest
fallback:
- provider: openai
model: gpt-4o
- provider: google
model: gemini-2.0-flash-exp
```
Budget Controls [#budget-controls]
```yaml
budget:
claude-code:
limits:
hourly: 5.00
daily: 50.00
alerts:
- at: 80%
action: notify
- at: 100%
action: block
```
Common Recipes [#common-recipes]
Recipe: Cost-Optimized Development [#recipe-cost-optimized-development]
```yaml
# Route by task complexity
routes:
- match: "claude-code/*"
rules:
- if: complexity == "simple"
model: gpt-4o-mini
- if: complexity == "moderate"
model: claude-3-5-haiku-latest
- if: complexity == "complex"
model: claude-3-5-sonnet-latest
```
Recipe: Team Collaboration [#recipe-team-collaboration]
```bash
# Export team config
bitrouter config export > team-config.yaml
# Team members import
bitrouter config import team-config.yaml
```
Recipe: MCP Tools Access [#recipe-mcp-tools-access]
```yaml
mcp_servers:
- name: github
command: npx @modelcontextprotocol/server-github
- name: filesystem
command: npx @modelcontextprotocol/server-filesystem
args: ["--root", "/code"]
routes:
- match: "claude-code/*"
mcp_access: [github, filesystem]
```
CLAUDE.md Configuration [#claudemd-configuration]
Enhance Claude Code's behavior with a project-specific config:
```markdown
# Project Configuration
## BitRouter Settings
- Use `claude-code/test/*` route for test generation
- Use `claude-code/docs/*` route for documentation
- Use `claude-code/refactor/*` route for major refactoring
## Coding Standards
- Follow existing code style
- Write comprehensive tests
- Document complex logic
```
Monitoring [#monitoring]
Real-time Session Tracking [#real-time-session-tracking]
```bash
# View active sessions
bitrouter sessions list --agent claude-code
# Monitor live session
bitrouter monitor --agent claude-code --live
# Export session data
bitrouter sessions export --format json
```
Cost Analytics [#cost-analytics]
```bash
# Current spending
bitrouter costs show --agent claude-code
# Daily breakdown
bitrouter costs breakdown --agent claude-code --by day
# Set spending alert
bitrouter budget alert --agent claude-code --at 80%
```
Troubleshooting [#troubleshooting]
🔴 Connection Issues [#-connection-issues]
```bash
# Verify BitRouter is running
curl http://localhost:8787/health
# Check Claude Code config
claude config show
# Test with debug mode
RUST_LOG=debug bitrouter serve
claude --verbose
```
🟡 Performance Problems [#-performance-problems]
```bash
# Benchmark providers
bitrouter providers benchmark
# Enable caching
bitrouter config set cache.enabled true
# Optimize routing
bitrouter routes optimize --agent claude-code
```
🔵 Authentication Errors [#-authentication-errors]
```bash
# Validate all API keys
bitrouter config validate
# Test specific provider
bitrouter providers test anthropic
# Re-authenticate
claude auth refresh
```
Advanced Features [#advanced-features]
Context Window Management [#context-window-management]
```yaml
routes:
- match: "claude-code/*"
options:
max_tokens: 8192
compress_context: true
cache_enabled: true
```
Custom Hooks [#custom-hooks]
```yaml
hooks:
pre_request:
- name: security_scan
command: ./scan_request.sh
post_response:
- name: log_activity
command: ./log_activity.sh
```
Learn More [#learn-more]
* 📚 [Claude Code Documentation](https://docs.anthropic.com/claude-code)
* 🎯 [BitRouter Skills](https://github.com/bitrouter/claude-code-skills)
* 💡 [Example Configs](https://github.com/bitrouter/examples/claude-code)
* 💬 [Discord Community](https://discord.gg/G3zVrZDa5C)
# Codex (/zh/docs/cookbook/integration/codex)
Codex Integration [#codex-integration]
Quick Start [#quick-start]
```bash
# 1. Start BitRouter
bitrouter serve
# 2. Configure Codex CLI
codex config set api.base http://localhost:8787
# 3. Launch Codex
codex init
```
What You Get [#what-you-get]
* ✅ **Multi-provider routing** - Beyond OpenAI models to Anthropic, Google, etc.
* ✅ **Local control** - Manage cloud operations from your proxy
* ✅ **Cost tracking** - Monitor parallel execution spending
* ✅ **Fallback providers** - Never blocked by OpenAI limits
* ✅ **Enhanced security** - Guardrails at the proxy layer
Installation [#installation]
Prerequisites [#prerequisites]
```bash
# Install Codex CLI
npm i -g @openai/codex
# Or use desktop app
# Download from chatgpt.com/codex
```
Connect to BitRouter [#connect-to-bitrouter]
Choose your setup:
Option 1: CLI Configuration [#option-1-cli-configuration]
```bash
codex config set api.base http://localhost:8787
codex config set api.protocol openai
codex init
```
Option 2: Desktop App [#option-2-desktop-app]
```bash
export OPENAI_API_BASE=http://localhost:8787
codex-app
```
Option 3: Browser Extension [#option-3-browser-extension]
```javascript
// In browser console
localStorage.setItem('codex_api_base', 'http://localhost:8787');
```
Essential Configuration [#essential-configuration]
Smart Routing by Task [#smart-routing-by-task]
```yaml
# ~/.bitrouter/config.yaml
routes:
# Main Codex operations
- match: "codex/main/*"
provider: openai
model: codex-1
# Code review & analysis
- match: "codex/review/*"
provider: anthropic
model: claude-3-5-sonnet-latest
# Test generation
- match: "codex/test/*"
provider: deepseek
model: deepseek-coder
# Documentation
- match: "codex/docs/*"
provider: google
model: gemini-2.0-flash-exp
```
Parallel Execution Support [#parallel-execution-support]
```yaml
routes:
- match: "codex/parallel/*"
provider: openai
model: codex-1
options:
max_parallel: 5
timeout: 300s
load_balancing:
strategy: round_robin
```
Automation Workflows [#automation-workflows]
```yaml
automations:
issue_triage:
route: "codex/automation/triage"
provider: openai
model: gpt-4o
schedule: "*/15 * * * *"
ci_monitoring:
route: "codex/automation/ci"
provider: anthropic
model: claude-3-5-haiku-latest
trigger: webhook
```
Common Recipes [#common-recipes]
Recipe: High Availability [#recipe-high-availability]
```yaml
routes:
- match: "codex/*"
provider: openai
model: codex-1
fallback:
- provider: anthropic
model: claude-3-5-sonnet-latest
- provider: google
model: gemini-2.0-flash-exp
```
Recipe: Cost Optimization [#recipe-cost-optimization]
```yaml
cloud_resources:
cost_limits:
hourly: 50.00
daily: 500.00
auto_scale:
enabled: true
min_instances: 2
max_instances: 20
```
Recipe: Skills Integration [#recipe-skills-integration]
```yaml
skills:
routing:
- skill: "code-understanding"
provider: openai
model: codex-1
- skill: "prototyping"
provider: anthropic
model: claude-3-5-sonnet-latest
```
Monitoring [#monitoring]
Session Tracking [#session-tracking]
```bash
# List Codex sessions
bitrouter sessions list --agent codex
# View parallel execution
bitrouter codex status --show-parallel
# Export metrics
bitrouter sessions export --agent codex --format csv
```
Cost Analytics [#cost-analytics]
```bash
# Spending breakdown
bitrouter costs breakdown --agent codex
# Set budget alert
bitrouter budget set --agent codex --daily 100
# Generate report
bitrouter report generate --agent codex --period month
```
Troubleshooting [#troubleshooting]
🔴 Connection Failed [#-connection-failed]
```bash
# Check BitRouter
curl http://localhost:8787/health
# Verify Codex config
codex config list
# Reset API base
codex config set api.base http://localhost:8787
```
🟡 Cloud Environment Issues [#-cloud-environment-issues]
```bash
# Test connectivity
bitrouter providers test openai
# Check credentials
codex auth status
# Restart Codex
codex restart
```
🔵 Performance Problems [#-performance-problems]
```bash
# Analyze routing
bitrouter performance analyze --agent codex
# Optimize routes
bitrouter routes optimize --agent codex
# Clear cache
bitrouter cache clear --agent codex
```
Advanced Features [#advanced-features]
Environment Routing [#environment-routing]
```yaml
environments:
development:
route: "codex/dev/*"
provider: openai
model: gpt-4o
production:
route: "codex/prod/*"
provider: openai
model: codex-1
guardrails:
- approval_required
- audit_log
```
Security Guardrails [#security-guardrails]
```yaml
guardrails:
codex:
- type: secret_detection
action: redact
- type: pii_protection
action: block
- type: code_security
scan_for: [sql_injection, xss]
```
Learn More [#learn-more]
* 📚 [Codex Documentation](https://platform.openai.com/docs/guides/codex)
* 🔧 [BitRouter Codex Skills](https://github.com/bitrouter/codex-skills)
* 💡 [Cloud Integration Examples](https://github.com/bitrouter/examples/codex)
* 💬 [Discord Community](https://discord.gg/G3zVrZDa5C)
# GitHub Copilot (/zh/docs/cookbook/integration/github-copilot)
GitHub Copilot Integration [#github-copilot-integration]
Quick Start [#quick-start]
```bash
# 1. Start BitRouter
bitrouter serve
# 2. Add to VS Code settings.json
# "github.copilot.advanced": {
# "debug.overrideProxyUrl": "http://localhost:8787"
# }
# 3. Reload VS Code — Copilot now routes through BitRouter
```
What You Get [#what-you-get]
* ✅ **25+ LLM providers** - Route Copilot requests through any BitRouter provider
* ✅ **VS Code + CLI** - Both the extension and `gh copilot` CLI are supported
* ✅ **Cost tracking** - Monitor spending across all Copilot sessions
* ✅ **BYOK support** - Bring your own API keys for Business/Enterprise plans
* ✅ **Fallback routing** - Automatic failover when a provider is unavailable
Installation [#installation]
Prerequisites [#prerequisites]
```bash
# VS Code extension — search "GitHub Copilot" in Extensions panel
# or install via CLI:
code --install-extension GitHub.copilot
# GitHub Copilot CLI (optional)
gh extension install github/gh-copilot
```
Connect to BitRouter [#connect-to-bitrouter]
Choose your approach based on your VS Code version and Copilot plan:
Option 1: Debug Proxy Override (Stable VS Code, any plan) [#option-1-debug-proxy-override-stable-vs-code-any-plan]
```json
// .vscode/settings.json or user settings
{
"github.copilot.advanced": {
"debug.overrideProxyUrl": "http://localhost:8787",
"debug.testOverrideProxyUrl": "http://localhost:8787"
}
}
```
Reload VS Code after saving. This routes all Copilot completions and chat through BitRouter.
Option 2: BYOK Custom Endpoint (VS Code Insiders, Business/Enterprise) [#option-2-byok-custom-endpoint-vs-code-insiders-businessenterprise]
```json
// chatLanguageModels.json (Command Palette: "Chat: Manage Language Models")
[
{
"name": "BitRouter",
"vendor": "customendpoint",
"apiKey": "your-bitrouter-key",
"apiType": "chat-completions",
"models": [
{
"id": "claude-3-5-sonnet-latest",
"name": "BitRouter → Claude 3.5 Sonnet",
"url": "http://localhost:8787/v1/chat/completions",
"toolCalling": true,
"vision": false,
"maxInputTokens": 200000,
"maxOutputTokens": 8192
},
{
"id": "gpt-4o",
"name": "BitRouter → GPT-4o",
"url": "http://localhost:8787/v1/chat/completions",
"toolCalling": true,
"vision": true,
"maxInputTokens": 128000,
"maxOutputTokens": 4096
}
]
}
]
```
Option 3: Copilot CLI (gh copilot) [#option-3-copilot-cli-gh-copilot]
```bash
export COPILOT_PROVIDER_BASE_URL="http://localhost:8787/v1"
export COPILOT_MODEL="claude-3-5-sonnet-latest"
export COPILOT_PROVIDER_API_KEY="your-bitrouter-key"
export COPILOT_OFFLINE="true" # prevent silent fallback to GitHub-hosted models
gh copilot suggest "create a docker-compose for a postgres + redis stack"
gh copilot explain "$(cat main.go)"
```
Essential Configuration [#essential-configuration]
Multi-Provider Routing [#multi-provider-routing]
```yaml
# ~/.bitrouter/config.yaml
routes:
# Copilot completions — fast, cheap model
- match: "copilot/completions/*"
provider: openai
model: gpt-4o-mini
# Copilot Chat — more capable model
- match: "copilot/chat/*"
provider: anthropic
model: claude-3-5-sonnet-latest
# Complex refactoring tasks
- match: "copilot/chat/refactor/*"
provider: openai
model: o1-preview
# Local models via Ollama
- match: "copilot/local/*"
provider: ollama
model: codellama:34b
endpoint: http://localhost:11434
```
HTTP Proxy (Network-Level) [#http-proxy-network-level]
For corporate environments that need all traffic routed through a proxy:
```json
{
"http.proxy": "http://localhost:8787",
"http.proxySupport": "on",
"http.proxyStrictSSL": false
}
```
```bash
# Or via environment variables
export HTTPS_PROXY=http://localhost:8787
export HTTP_PROXY=http://localhost:8787
```
Cost Budgets [#cost-budgets]
```yaml
budgets:
copilot:
daily: 10.00
per_session: 2.00
alert_threshold: 0.80 # alert at 80% of budget
```
Common Recipes [#common-recipes]
Recipe: Inline Completions vs Chat Routing [#recipe-inline-completions-vs-chat-routing]
```yaml
routes:
# Fast, low-latency for inline completions
- match: "copilot/completions/*"
provider: openai
model: gpt-4o-mini
max_latency_ms: 800
# Full-context chat with Claude
- match: "copilot/chat/*"
provider: anthropic
model: claude-3-5-sonnet-latest
```
Recipe: Fallback Chain [#recipe-fallback-chain]
```yaml
routes:
- match: "copilot/*"
provider: anthropic
model: claude-3-5-sonnet-latest
fallback:
- provider: openai
model: gpt-4o
- provider: deepseek
model: deepseek-coder
```
Recipe: Cost-Optimized Setup [#recipe-cost-optimized-setup]
```yaml
routes:
- match: "copilot/*"
rules:
- if: context_tokens < 4000
provider: openai
model: gpt-4o-mini
- if: context_tokens >= 4000
provider: deepseek
model: deepseek-coder
```
Monitoring [#monitoring]
Usage Dashboard [#usage-dashboard]
```bash
# Copilot session summary
bitrouter sessions list --agent copilot
# Token usage by model
bitrouter usage breakdown --agent copilot --group-by model
# Daily spend
bitrouter costs breakdown --agent copilot --period day
```
Latency Tracking [#latency-tracking]
```bash
# P95 latency per route
bitrouter stats latency --agent copilot
# Provider comparison
bitrouter providers benchmark --agent copilot
```
Troubleshooting [#troubleshooting]
🔴 Copilot Not Using BitRouter [#-copilot-not-using-bitrouter]
```bash
# Verify BitRouter is running
curl http://localhost:8787/health
# Check VS Code setting is saved
code --list-extensions | grep copilot
# Open settings.json, confirm debug.overrideProxyUrl is set
# Reload VS Code window
# Command Palette: "Developer: Reload Window"
```
🟡 BYOK Endpoint Not Appearing in Chat [#-byok-endpoint-not-appearing-in-chat]
```bash
# Confirm you're on VS Code Insiders with a Business/Enterprise plan
# Open Command Palette: "Chat: Manage Language Models"
# Re-enter the chatLanguageModels.json configuration
# Test the endpoint directly
curl http://localhost:8787/v1/models
```
🔵 Copilot CLI Falling Back to Cloud [#-copilot-cli-falling-back-to-cloud]
```bash
# Ensure COPILOT_OFFLINE=true is set
echo $COPILOT_OFFLINE
# Verify base URL includes /v1
echo $COPILOT_PROVIDER_BASE_URL # should end with /v1
# Test the endpoint
curl http://localhost:8787/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"gpt-4o","messages":[{"role":"user","content":"hello"}]}'
```
Advanced Features [#advanced-features]
Workspace-Scoped Routing [#workspace-scoped-routing]
```json
// .vscode/settings.json (project-level, overrides user settings)
{
"github.copilot.advanced": {
"debug.overrideProxyUrl": "http://localhost:8787"
}
}
```
Commit this to your repo so every team member routes through the shared BitRouter instance.
Enterprise Proxy with Auth [#enterprise-proxy-with-auth]
```yaml
# ~/.bitrouter/config.yaml
providers:
copilot_enterprise:
type: github_copilot
enterprise_url: https://github.yourcompany.com
auth: bearer
route_prefix: "copilot/enterprise/*"
```
Model Overrides by File Type [#model-overrides-by-file-type]
```yaml
routes:
- match: "copilot/*"
rules:
- if: file_extension in [".py", ".ipynb"]
model: deepseek-coder-v2
- if: file_extension in [".rs", ".go"]
model: claude-3-5-sonnet-latest
- default:
model: gpt-4o-mini
```
Learn More [#learn-more]
* 📚 [GitHub Copilot Docs](https://docs.github.com/en/copilot)
* 🔧 [Copilot Network Settings](https://docs.github.com/en/copilot/managing-copilot/configure-personal-settings/configuring-network-settings-for-github-copilot)
* 🔑 [BYOK / Custom Endpoints](https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-enterprise/use-your-own-api-keys)
* 🖥️ [Copilot CLI BYOK](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/use-byok-models)
* 💬 [Discord Community](https://discord.gg/G3zVrZDa5C)
# Hermes (/zh/docs/cookbook/integration/hermes)
Hermes Integration [#hermes-integration]
Quick Start [#quick-start]
```bash
# 1. Start BitRouter with memory support
bitrouter acp --enable-memory
# 2. Configure Hermes
hermes config set backend bitrouter
hermes config set bitrouter.url http://localhost:8787
# 3. Launch with persistent memory
hermes start --memory persistent
```
What You Get [#what-you-get]
* ✅ **Persistent memory** - Learning that survives restarts
* ✅ **Multi-provider learning** - Diverse model experiences
* ✅ **Cost-optimized sessions** - Smart routing for long runs
* ✅ **Learning trajectories** - Track improvement over time
* ✅ **Research-ready** - Batch processing and exports
Installation [#installation]
Prerequisites [#prerequisites]
```bash
# Install Hermes
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
# Verify 64k+ context models available
bitrouter models list --min-context 64000
```
Connect to BitRouter [#connect-to-bitrouter]
Choose your backend:
Option 1: ACP Integration (Recommended) [#option-1-acp-integration-recommended]
```bash
hermes config set backend bitrouter
hermes config set protocol acp
hermes config set bitrouter.url http://localhost:8787
hermes start --memory persistent
```
Option 2: Direct API [#option-2-direct-api]
```bash
export HERMES_API_BASE=http://localhost:8787
hermes start --provider custom
```
Option 3: Multi-Backend [#option-3-multi-backend]
```bash
hermes config set backends.primary bitrouter
hermes config set backends.primary.url http://localhost:8787
hermes start --multi-backend
```
Essential Configuration [#essential-configuration]
Memory-Optimized Routing [#memory-optimized-routing]
```yaml
# ~/.bitrouter/config.yaml
routes:
# Learning operations - large context
- match: "hermes/learn/*"
provider: anthropic
model: claude-3-5-sonnet-latest
options:
max_tokens: 200000
# Memory recall - fast access
- match: "hermes/recall/*"
provider: openai
model: gpt-4o
cache:
enabled: true
ttl: 3600
# Self-improvement cycles
- match: "hermes/improve/*"
provider: anthropic
model: claude-3-5-sonnet-latest
options:
temperature: 0.9
```
Persistent Memory Setup [#persistent-memory-setup]
```yaml
memory:
hermes:
type: persistent
backend: bitrouter
storage:
path: ~/.hermes/memory
encryption: true
sync:
enabled: true
interval: 300s
namespaces:
- name: general
max_size: 10MB
- name: code
max_size: 50MB
```
Learning Cycles [#learning-cycles]
```yaml
learning:
cycles:
- name: "daily_review"
schedule: "0 0 * * *"
route: "hermes/learn/review"
model: claude-3-5-sonnet-latest
- name: "skill_improvement"
trigger: performance_threshold
route: "hermes/learn/skills"
```
Common Recipes [#common-recipes]
Recipe: Research Mode [#recipe-research-mode]
```yaml
research:
enabled: true
trajectory_export: true
batch_processing: true
routing:
control: "hermes/research/control"
treatment: "hermes/research/treatment"
```
Recipe: Multi-Platform Memory [#recipe-multi-platform-memory]
```yaml
platforms:
telegram:
route: "hermes/telegram/*"
memory_namespace: "telegram"
discord:
route: "hermes/discord/*"
memory_namespace: "discord"
```
Recipe: Context Optimization [#recipe-context-optimization]
```yaml
context:
hermes:
strategy: sliding_window
window_sizes:
small: 8192
medium: 32768
large: 128000
auto_adjust: true
```
Backend Options [#backend-options]
Local Backend [#local-backend]
```bash
# Docker backend
hermes backend start --type docker \
--routing http://localhost:8787
```
SSH Backend [#ssh-backend]
```bash
# Remote compute
hermes backend start --type ssh \
--host compute.example.com \
--tunnel 8787:8787
```
Cloud Backends [#cloud-backends]
```bash
# Modal backend
hermes backend start --type modal \
--app hermes-agent
# Singularity backend
hermes backend start --type singularity \
--image hermes.sif
```
Monitoring [#monitoring]
Memory Analytics [#memory-analytics]
```bash
# Memory usage
bitrouter memory stats --agent hermes
# Memory patterns
bitrouter memory analyze --agent hermes --period week
# Export snapshot
bitrouter memory export --agent hermes --format json
```
Learning Progress [#learning-progress]
```bash
# Track metrics
bitrouter learning progress --agent hermes
# View improvement
bitrouter learning chart --agent hermes --metric accuracy
# Export data
bitrouter learning export --agent hermes --format csv
```
Troubleshooting [#troubleshooting]
🔴 Memory Not Persisting [#-memory-not-persisting]
```bash
# Check memory backend
hermes memory status
# Verify BitRouter support
bitrouter features list | grep memory
# Test memory ops
hermes memory test --verbose
```
🟡 Context Window Errors [#-context-window-errors]
```bash
# Check model capabilities
bitrouter models list --min-context 64000
# Adjust context
hermes config set max_context 128000
# Enable compression
bitrouter config set compression.enabled true
```
🔵 Learning Loop Failures [#-learning-loop-failures]
```bash
# Check learning status
hermes learning status
# View error logs
bitrouter logs --filter "hermes/learn"
# Reset learning state
hermes learning reset --confirm
```
Advanced Features [#advanced-features]
Multi-Model Ensemble [#multi-model-ensemble]
```yaml
ensemble:
hermes:
models:
- provider: anthropic
model: claude-3-5-sonnet-latest
weight: 0.4
- provider: openai
model: gpt-4o
weight: 0.3
- provider: google
model: gemini-1.5-pro
weight: 0.3
```
Skills Integration [#skills-integration]
```yaml
skills:
source: agentskills.io
routing:
- skill: "code-generation"
route: "hermes/skills/code"
model: deepseek-coder
- skill: "research"
route: "hermes/skills/research"
model: gpt-4o
```
Learn More [#learn-more]
* 📚 [Hermes Documentation](https://github.com/NousResearch/hermes-agent)
* 🧠 [Memory Guide](https://bitrouter.ai/docs/memory)
* 🔬 [Research Examples](https://github.com/bitrouter/examples/hermes)
* 💬 [Discord Community](https://discord.gg/G3zVrZDa5C)
# 代理集成 (/zh/docs/cookbook/integration)
代理集成 [#代理集成]
将您喜爱的 AI 代理连接到 BitRouter 的智能路由层。
快速集成矩阵 [#快速集成矩阵]
| 代理 | 类型 | 最适合 | 设置时间 |
| ------------------------------------------------------------ | --------- | ------- | ---- |
| [**Claude Code**](/zh/docs/cookbook/integration/claude-code) | IDE + CLI | 企业开发 | 2 分钟 |
| [**Cline**](/zh/docs/cookbook/integration/cline) | VS Code | 人机协作编码 | 2 分钟 |
| [**Openclaw**](/zh/docs/cookbook/integration/openclaw) | 多渠道 | 聊天平台机器人 | 5 分钟 |
| [**Pi**](/zh/docs/cookbook/integration/pi) | 终端 | 最简化、可扩展 | 3 分钟 |
| [**Opencode**](/zh/docs/cookbook/integration/opencode) | 终端 + IDE | 提供商无关 | 3 分钟 |
| [**Goose**](/zh/docs/cookbook/integration/goose) | MCP 专注 | 工具编排 | 5 分钟 |
| [**Codex**](/zh/docs/cookbook/integration/codex) | 云端 | 并行执行 | 3 分钟 |
| [**KiloCode**](/zh/docs/cookbook/integration/kilocode) | 多代理 | 基于角色的团队 | 5 分钟 |
| [**Hermes**](/zh/docs/cookbook/integration/hermes) | 研究 | 持久记忆 | 5 分钟 |
通用快速开始 [#通用快速开始]
适用于大多数代理：
```bash
# 1. 启动 BitRouter
bitrouter serve
# 2. 设置 API 端点
export AGENT_API_BASE=http://localhost:8787
# 3. 启动您的代理
your-agent-command
```
集成方法 [#集成方法]
方法 1：API 代理（简单） [#方法-1api-代理简单]
将您的代理指向 BitRouter 的 OpenAI 兼容端点。
方法 2：ACP 协议（高级） [#方法-2acp-协议高级]
使用代理通信协议进行发现和协调。
方法 3：原生插件 [#方法-3原生插件]
直接在您的代理运行时中安装 BitRouter 插件。
未列出？ [#未列出]
大多数支持自定义 OpenAI 或 Anthropic 基础 URL 的代理都可以与 BitRouter 开箱即用。查看我们的[通用集成指南](/zh/docs/guides/overview/quickstart)获取通用设置说明。
# KiloCode (/zh/docs/cookbook/integration/kilocode)
KiloCode Integration [#kilocode-integration]
Quick Start [#quick-start]
```bash
# 1. Start BitRouter
bitrouter serve
# 2. Configure KiloCode CLI
kilocode config set api.base http://localhost:8787
# 3. Launch KiloCode
kilocode start --router bitrouter
```
What You Get [#what-you-get]
* ✅ **Multi-agent routing** - Route Architect, Coder, Debugger, Analyst separately
* ✅ **Budget dashboard** - Enhanced expense tracking with BitRouter
* ✅ **500+ model support** - All through BitRouter's unified interface
* ✅ **Smart loop breaking** - Prevent infinite loops across providers
* ✅ **Role-based optimization** - Optimal models per agent specialization
Installation [#installation]
Prerequisites [#prerequisites]
```bash
# Install KiloCode (choose one)
code --install-extension kilocode # VS Code
npm install -g @kilocode/cli # CLI
# Download desktop app from kilocode.ai
```
Connect to BitRouter [#connect-to-bitrouter]
Choose your setup:
Option 1: VS Code Extension [#option-1-vs-code-extension]
```json
// .vscode/settings.json
{
"kilocode.apiBase": "http://localhost:8787",
"kilocode.routing": "bitrouter"
}
```
Option 2: CLI Configuration [#option-2-cli-configuration]
```bash
kilocode config set api.base http://localhost:8787
kilocode config set routing.enabled true
kilocode start --router bitrouter
```
Option 3: Desktop App [#option-3-desktop-app]
```bash
export KILOCODE_API_BASE=http://localhost:8787
kilocode-app
```
Essential Configuration [#essential-configuration]
Role-Based Agent Routing [#role-based-agent-routing]
```yaml
# ~/.bitrouter/config.yaml
routes:
# Architect - planning & design
- match: "kilocode/architect/*"
provider: anthropic
model: claude-3-5-sonnet-latest
options:
temperature: 0.3
# Coder - implementation
- match: "kilocode/coder/*"
provider: openai
model: gpt-4o
options:
temperature: 0.2
# Debugger - fixing issues
- match: "kilocode/debugger/*"
provider: deepseek
model: deepseek-coder
options:
temperature: 0.1
# Analyst - analysis & questions
- match: "kilocode/analyst/*"
provider: google
model: gemini-2.0-flash-exp
options:
temperature: 0.5
```
Budget Management [#budget-management]
```yaml
budget:
kilocode:
limits:
hourly: 10.00
daily: 100.00
monthly: 2000.00
per_agent_limits:
architect: 30.00/day
coder: 40.00/day
debugger: 20.00/day
analyst: 10.00/day
alerts:
- threshold: 80%
action: notify
- threshold: 100%
action: block
```
Loop Breaking & Safety [#loop-breaking--safety]
```yaml
loop_breaker:
kilocode:
enabled: true
detection:
max_iterations: 10
similarity_threshold: 0.9
time_limit: 300s
actions:
- detect: infinite_loop
action: terminate
- detect: repetitive_output
action: switch_model
- detect: cost_spiral
action: pause
```
Common Recipes [#common-recipes]
Recipe: Development Phase Modes [#recipe-development-phase-modes]
```yaml
modes:
kilocode:
planning:
primary_agent: architect
route: "kilocode/mode/planning/*"
model: claude-3-5-sonnet-latest
implementation:
primary_agent: coder
route: "kilocode/mode/coding/*"
model: gpt-4o
debugging:
primary_agent: debugger
route: "kilocode/mode/debug/*"
model: deepseek-coder
```
Recipe: Cost Dashboard [#recipe-cost-dashboard]
```yaml
dashboard:
kilocode:
metrics:
- total_cost
- cost_per_agent
- cost_per_model
- tokens_used
export:
format: csv
schedule: daily
```
Recipe: Multi-IDE Support [#recipe-multi-ide-support]
```yaml
ide_support:
vscode:
route_prefix: "kilocode/vscode"
features: [inline_completions, sidebar_chat, diff_view]
jetbrains:
route_prefix: "kilocode/jetbrains"
features: [code_inspections, refactoring, quick_fixes]
windsurf:
route_prefix: "kilocode/windsurf"
features: [cascade_mode, parallel_edits]
```
Browser Automation [#browser-automation]
Web Development Support [#web-development-support]
```yaml
browser:
kilocode:
enabled: true
automation:
route: "kilocode/browser/*"
provider: openai
model: gpt-4o-vision
capabilities:
- dom_manipulation
- form_filling
- screenshot_analysis
safety:
sandbox_mode: true
max_actions_per_session: 50
```
Monitoring [#monitoring]
Agent Performance [#agent-performance]
```bash
# Monitor agents
bitrouter agents monitor --name kilocode
# Per-agent stats
bitrouter agents stats --breakdown-by-role
# Export performance
bitrouter agents export --name kilocode --format json
```
Budget Analytics [#budget-analytics]
```bash
# Current spending
kilocode budget status
# Spending breakdown
bitrouter costs breakdown --agent kilocode --group-by role
# Set alerts
bitrouter budget alert --agent kilocode --threshold 80%
```
Troubleshooting [#troubleshooting]
🔴 Agent Not Responding [#-agent-not-responding]
```bash
# Check agent status
kilocode agents status
# Verify BitRouter
curl http://localhost:8787/health
# Restart specific agent
kilocode agent restart --name architect
```
🟡 Budget Exceeded [#-budget-exceeded]
```bash
# Check usage
kilocode budget usage
# Adjust limits
bitrouter budget set --agent kilocode --daily 150
# Reset counter
kilocode budget reset --confirm
```
🔵 Loop Detection Triggering [#-loop-detection-triggering]
```bash
# View logs
bitrouter logs --filter "loop_detection"
# Adjust sensitivity
kilocode config set loop_detection.sensitivity medium
# Disable for debugging
kilocode config set loop_detection.enabled false
```
Advanced Features [#advanced-features]
Custom Agent Roles [#custom-agent-roles]
```yaml
custom_agents:
kilocode:
- name: "security-auditor"
route: "kilocode/custom/security/*"
model: claude-3-5-sonnet-latest
capabilities: [vulnerability_scanning, code_audit]
- name: "performance-optimizer"
route: "kilocode/custom/performance/*"
model: gpt-4o
capabilities: [profiling, optimization]
```
File Protection [#file-protection]
```yaml
security:
kilocode:
file_freezing:
enabled: true
protected_patterns:
- "*.env"
- "**/secrets/*"
- "**/config/production/*"
freeze_on:
- production_branch
- sensitive_files
```
Learn More [#learn-more]
* 📚 [KiloCode Documentation](https://docs.kilocode.ai)
* 🎯 [Agent Roles Guide](https://kilocode.ai/best-practices)
* 💡 [Integration Examples](https://github.com/bitrouter/kilocode-integration)
* 💬 [Discord Community](https://discord.gg/G3zVrZDa5C)
# Openclaw (/zh/docs/cookbook/integration/openclaw)
Openclaw Integration [#openclaw-integration]
Quick Start [#quick-start]
```bash
# 1. Start BitRouter
bitrouter serve
# 2. Install Openclaw plugin
openclaw plugins install bitrouter
# 3. Configure and launch
openclaw config set provider bitrouter
openclaw start --provider bitrouter
```
What You Get [#what-you-get]
* ✅ **20+ messaging platforms** - WhatsApp, Telegram, Slack, Discord, etc.
* ✅ **Multi-provider routing** - Optimize models per platform
* ✅ **Native plugin support** - Seamless BitRouter integration
* ✅ **Isolated workspaces** - Separate contexts per channel
* ✅ **Cost tracking** - Monitor spending across all platforms
Installation [#installation]
Prerequisites [#prerequisites]
```bash
# Install Openclaw
npm install -g openclaw@latest
# Quick setup
openclaw onboard --install-daemon
```
Connect to BitRouter [#connect-to-bitrouter]
Choose your method:
Option 1: Native Plugin (Recommended) [#option-1-native-plugin-recommended]
```bash
openclaw plugins install bitrouter
openclaw config set provider bitrouter
openclaw config set bitrouter.url http://localhost:8787
openclaw start
```
Option 2: ACP Integration [#option-2-acp-integration]
```bash
openclaw config set protocol acp
openclaw config set acp.endpoint http://localhost:8787
openclaw acp
```
Option 3: Direct API [#option-3-direct-api]
```bash
openclaw config set api.base http://localhost:8787
openclaw start
```
Essential Configuration [#essential-configuration]
Platform-Specific Routing [#platform-specific-routing]
```yaml
# ~/.bitrouter/config.yaml
routes:
# WhatsApp - conversational
- match: "openclaw/whatsapp/*"
provider: anthropic
model: claude-3-5-haiku-latest
options:
temperature: 0.8
# Slack - professional
- match: "openclaw/slack/*"
provider: openai
model: gpt-4o
options:
temperature: 0.3
# Discord - community
- match: "openclaw/discord/*"
provider: deepseek
model: deepseek-chat
# Telegram - quick
- match: "openclaw/telegram/*"
provider: google
model: gemini-2.0-flash-exp
```
Workspace Isolation [#workspace-isolation]
```yaml
workspaces:
- name: "enterprise-slack"
match: "openclaw/slack/enterprise/*"
provider: anthropic
model: claude-3-5-sonnet-latest
guardrails:
- data_isolation
- audit_logging
- name: "public-discord"
match: "openclaw/discord/public/*"
provider: openai
model: gpt-4o-mini
rate_limits:
requests_per_minute: 10
```
Skills Integration [#skills-integration]
```yaml
skills:
source: clawhub.ai
routing:
- skill: "code-review"
route: "openclaw/skills/review"
provider: anthropic
model: claude-3-5-sonnet-latest
- skill: "debug-assistance"
route: "openclaw/skills/debug"
provider: openai
model: gpt-4o
```
Common Recipes [#common-recipes]
Recipe: Multi-Channel Bot [#recipe-multi-channel-bot]
```yaml
platforms:
whatsapp:
route: "openclaw/whatsapp"
qr_code: true
slack:
route: "openclaw/slack"
oauth: true
telegram:
route: "openclaw/telegram"
bot_token: true
```
Recipe: Voice Support [#recipe-voice-support]
```yaml
voice:
wake_word: "hey openclaw"
transcription:
route: "openclaw/voice/transcribe"
model: whisper-large-v3
synthesis:
route: "openclaw/voice/synthesize"
model: tts-1-hd
```
Recipe: Live Canvas [#recipe-live-canvas]
```yaml
canvas:
enabled: true
route: "openclaw/canvas/*"
features:
- collaborative_editing
- real_time_sync
- version_control
```
Platform Setup [#platform-setup]
WhatsApp Business [#whatsapp-business]
```bash
# Connect via QR code
openclaw connect whatsapp
# Scan QR code with phone
```
Slack Integration [#slack-integration]
```bash
# OAuth setup
openclaw connect slack --workspace YOUR_WORKSPACE
# Follow OAuth flow
```
Discord Bot [#discord-bot]
```bash
# Bot token setup
openclaw connect discord --token YOUR_BOT_TOKEN
```
Monitoring [#monitoring]
Channel Activity [#channel-activity]
```bash
# View all channels
bitrouter dashboard --agent openclaw
# Channel metrics
bitrouter metrics --agent openclaw --channel whatsapp
# Export analytics
bitrouter export analytics --agent openclaw --format csv
```
Cost Tracking [#cost-tracking]
```bash
# Platform breakdown
bitrouter costs breakdown --group-by platform
# Set budgets
bitrouter budget set --platform whatsapp --daily 10
bitrouter budget set --platform slack --daily 50
```
Troubleshooting [#troubleshooting]
🔴 Connection Issues [#-connection-issues]
```bash
# Check BitRouter
curl http://localhost:8787/health
# Verify Openclaw
openclaw config show
# Test connection
openclaw test connection --provider bitrouter
```
🟡 Platform Failures [#-platform-failures]
```bash
# Debug platform
openclaw debug whatsapp
# Check logs
bitrouter logs --filter openclaw
# Verify credentials
openclaw platforms verify
```
🔵 Message Routing [#-message-routing]
```bash
# Trace message
bitrouter trace --message-id
# Test route
bitrouter routes test "openclaw/whatsapp/message"
# Monitor live
bitrouter monitor --agent openclaw --live
```
Advanced Features [#advanced-features]
Multi-Agent Routing [#multi-agent-routing]
```yaml
multi_agent:
- pattern: "openclaw/*/code/*"
agent: claude-code
- pattern: "openclaw/*/docs/*"
agent: opencode
```
Custom Skills [#custom-skills]
```bash
# Add skill
openclaw skills add custom-skill
# Configure routing
openclaw skills config custom-skill \
--route "openclaw/skills/custom" \
--provider "anthropic"
```
Learn More [#learn-more]
* 📚 [Openclaw Documentation](https://docs.openclaw.ai)
* 🔌 [BitRouter Plugin](https://github.com/bitrouter/bitrouter-openclaw)
* 🛒 [ClawHub Marketplace](https://clawhub.ai)
* 💬 [Discord Community](https://discord.gg/G3zVrZDa5C)
# Opencode (/zh/docs/cookbook/integration/opencode)
Opencode Integration [#opencode-integration]
Quick Start [#quick-start]
```bash
# 1. Start BitRouter
bitrouter serve
# 2. Configure Opencode for BitRouter
opencode config provider bitrouter
opencode config set bitrouter.url http://localhost:8787
# 3. Launch Opencode
opencode
```
What You Get [#what-you-get]
* ✅ **75+ provider support** - All through BitRouter's unified interface
* ✅ **Terminal-first design** - Clean TUI with BitRouter integration
* ✅ **Provider switching** - Seamlessly swap between models
* ✅ **Session persistence** - Save/restore with JSONL format
* ✅ **LSP integration** - Enhanced code understanding
Installation [#installation]
Prerequisites [#prerequisites]
```bash
# Install Opencode
curl -fsSL https://opencode.ai/install | bash
# Or via package manager
npm install -g @opencode/cli
# brew install opencode
```
Connect to BitRouter [#connect-to-bitrouter]
Choose your mode:
Option 1: Native Integration [#option-1-native-integration]
```bash
opencode config provider bitrouter
opencode config set bitrouter.url http://localhost:8787
opencode
```
Option 2: BYOK Mode [#option-2-byok-mode]
```bash
opencode config mode byok
opencode config set api.base http://localhost:8787
opencode
```
Option 3: Zen + BitRouter [#option-3-zen--bitrouter]
```bash
opencode config mode zen
opencode config set zen.proxy http://localhost:8787
opencode --hybrid-routing
```
Essential Configuration [#essential-configuration]
Provider-Agnostic Routing [#provider-agnostic-routing]
```yaml
# ~/.bitrouter/config.yaml
routes:
# Main coding tasks
- match: "opencode/code/*"
provider: anthropic
model: claude-3-5-sonnet-latest
# Quick operations
- match: "opencode/quick/*"
provider: openai
model: gpt-4o-mini
# Local models via Ollama
- match: "opencode/local/*"
provider: ollama
model: codellama:34b
endpoint: http://localhost:11434
```
Multi-Session Support [#multi-session-support]
```yaml
sessions:
opencode:
persistence: true
storage: ~/.opencode/sessions
features:
auto_save: true
branching: true
undo_redo: true
sharing: true
routing:
new: "opencode/session/new"
restore: "opencode/session/restore"
```
LSP Integration [#lsp-integration]
```yaml
lsp:
enabled: true
servers:
- language: python
command: pylsp
route: "opencode/lsp/python"
- language: typescript
command: typescript-language-server
route: "opencode/lsp/typescript"
- language: rust
command: rust-analyzer
route: "opencode/lsp/rust"
```
Common Recipes [#common-recipes]
Recipe: Cost-Optimized Development [#recipe-cost-optimized-development]
```yaml
routes:
- match: "opencode/*"
rules:
- if: task_type == "simple"
model: gpt-4o-mini
- if: task_type == "complex"
model: claude-3-5-sonnet-latest
```
Recipe: Multi-Provider Fallback [#recipe-multi-provider-fallback]
```yaml
routes:
- match: "opencode/*"
provider: anthropic
fallback:
- openai
- deepseek
- ollama
```
Recipe: Zen Mode Integration [#recipe-zen-mode-integration]
```yaml
zen:
enabled: true
models:
- name: "zen-coder"
route: "opencode/zen/coder"
fallback: "claude-3-5-sonnet-latest"
```
TUI Features [#tui-features]
Enhanced Terminal Interface [#enhanced-terminal-interface]
```yaml
tui:
opencode:
theme: catppuccin
features:
- syntax_highlighting
- multi_pane
- session_tabs
routing:
interactive: "opencode/tui/*"
```
Monitoring [#monitoring]
Session Analytics [#session-analytics]
```bash
# View Opencode sessions
bitrouter sessions list --agent opencode
# Monitor active session
bitrouter monitor --agent opencode --session
# Export session data
bitrouter export session --agent opencode --format json
```
Provider Performance [#provider-performance]
```bash
# Benchmark providers
bitrouter providers benchmark
# Provider switching stats
bitrouter providers stats --agent opencode
# Cost breakdown
bitrouter costs breakdown --agent opencode
```
Troubleshooting [#troubleshooting]
🔴 Connection Issues [#-connection-issues]
```bash
# Check BitRouter
curl http://localhost:8787/health
# Verify Opencode config
opencode config show
# Test connection
opencode test connection --provider bitrouter
```
🟡 Provider Switching [#-provider-switching]
```bash
# List providers
bitrouter providers list
# Test routing
bitrouter test route "opencode/test"
# Reset config
opencode config reset providers
```
🔵 Session Problems [#-session-problems]
```bash
# Check storage
ls -la ~/.opencode/sessions
# Clear corrupted
opencode sessions clear --corrupted
# Verify format
opencode sessions validate
```
Advanced Features [#advanced-features]
Undo/Redo System [#undoredo-system]
```yaml
history:
opencode:
enabled: true
max_depth: 100
routing:
undo: "opencode/history/undo"
redo: "opencode/history/redo"
```
MCP Integration [#mcp-integration]
```yaml
mcp:
opencode:
servers:
- name: filesystem
route: "opencode/mcp/fs"
- name: github
route: "opencode/mcp/github"
```
Custom Providers [#custom-providers]
```yaml
custom_providers:
opencode:
- name: "internal-llm"
endpoint: "https://llm.company.com"
route: "opencode/custom/*"
auth: bearer
```
Learn More [#learn-more]
* 📚 [Opencode Documentation](https://docs.opencode.ai)
* 🔄 [Provider Guide](https://opencode.ai/providers)
* 💡 [Integration Examples](https://github.com/bitrouter/opencode-integration)
* 💬 [Discord Community](https://discord.gg/G3zVrZDa5C)
# Pi Agent (/zh/docs/cookbook/integration/pi)
Pi Agent Integration [#pi-agent-integration]
Quick Start [#quick-start]
```bash
# 1. Start BitRouter
bitrouter serve
# 2. Configure Pi extension
pi config set ai.provider custom
pi config set ai.baseUrl http://localhost:8787
# 3. Launch Pi
pi
```
What You Get [#what-you-get]
* ✅ **Minimal & extensible** - Terminal-first with BitRouter routing
* ✅ **Extension system** - Custom tools and workflows through BitRouter
* ✅ **Session persistence** - Tree-structured JSONL sessions
* ✅ **Smart compaction** - Context management with cheaper models
* ✅ **Skills system** - On-demand capabilities via BitRouter
Installation [#installation]
Prerequisites [#prerequisites]
```bash
# Install Pi (choose one)
npm install -g @mariozechner/pi-coding-agent
# Clone from GitHub: github.com/earendil-works/pi
```
Connect to BitRouter [#connect-to-bitrouter]
Choose your method:
Option 1: Extension-Based [#option-1-extension-based]
```typescript
// pi-bitrouter-extension.ts
import { Extension } from '@earendil-works/pi-coding-agent';
export class BitRouterExtension extends Extension {
name = 'bitrouter';
async initialize(pi) {
pi.config.set('ai.provider', 'custom');
pi.config.set('ai.baseUrl', 'http://localhost:8787');
}
}
```
Option 2: Configuration File [#option-2-configuration-file]
```javascript
// ~/.pi/config.js
module.exports = {
ai: {
provider: 'custom',
baseUrl: 'http://localhost:8787',
model: 'auto', // Let BitRouter handle routing
},
extensions: ['@pi/bitrouter-extension']
};
```
Option 3: Environment Variables [#option-3-environment-variables]
```bash
export PI_AI_PROVIDER=custom
export PI_AI_BASE_URL=http://localhost:8787
pi
```
Essential Configuration [#essential-configuration]
Smart Task Routing [#smart-task-routing]
```yaml
# ~/.bitrouter/config.yaml
routes:
# Main coding operations
- match: "pi/code/*"
provider: anthropic
model: claude-3-5-sonnet-latest
# Quick operations
- match: "pi/quick/*"
provider: openai
model: gpt-4o-mini
# Complex tasks
- match: "pi/complex/*"
provider: openai
model: o1-preview
# Context compaction
- match: "pi/compaction/*"
provider: anthropic
model: claude-3-5-haiku-latest
```
Compaction & Context [#compaction--context]
```yaml
compaction:
pi:
enabled: true
strategy:
type: custom
route: "pi/compaction/*"
model: claude-3-5-haiku-latest
thresholds:
context_usage: 0.8
message_count: 50
preserve:
- code_blocks
- error_messages
- user_instructions
```
Session Management [#session-management]
```yaml
sessions:
pi:
structure: tree
persistence: jsonl
routing:
main: "pi/session/main/*"
branches: "pi/session/branch/*"
features:
auto_branch: true
session_replay: true
storage:
path: ~/.pi/sessions/
compression: true
```
Common Recipes [#common-recipes]
Recipe: Extension Development [#recipe-extension-development]
```typescript
// Enhanced BitRouter extension
export class BitRouterEnhanced extends Extension {
name = 'bitrouter-enhanced';
tools = [
{
name: 'route_optimize',
description: 'Optimize routing for task',
execute: async ({ task_type }) => {
const route = `pi/${task_type}/*`;
await this.pi.config.set('bitrouter.route', route);
return `Routing optimized for ${task_type}`;
}
}
];
}
```
Recipe: Skills Integration [#recipe-skills-integration]
```yaml
# skill.yaml
name: bitrouter-coding
description: Enhanced coding with BitRouter
instructions: |
Use BitRouter's intelligent routing:
- Complex algorithms: route through 'pi/complex'
- Quick edits: route through 'pi/quick'
- Documentation: route through 'pi/docs'
tools: [file_operations, bitrouter_routing]
```
Recipe: Package Distribution [#recipe-package-distribution]
```json
// package.json
{
"name": "@custom/pi-bitrouter",
"version": "1.0.0",
"pi": {
"extensions": ["./dist/extension.js"],
"skills": ["./skills"],
"themes": ["./themes/bitrouter.json"]
}
}
```
Theme Customization [#theme-customization]
BitRouter Status Theme [#bitrouter-status-theme]
```typescript
export const bitrouterTheme = {
name: 'bitrouter-status',
statusBar: {
left: ['mode', 'model'],
right: ['cost', 'latency', 'provider']
},
colors: {
primary: '#00A67E',
success: '#10B981',
warning: '#F59E0B'
},
indicators: {
routing: '🔀',
cached: '💾',
fallback: '🔄'
}
};
```
Monitoring [#monitoring]
Session Analytics [#session-analytics]
```bash
# Monitor Pi sessions
bitrouter sessions list --agent pi
# Real-time metrics
bitrouter monitor --agent pi --live
# Export analytics
bitrouter export analytics --agent pi --format csv
```
Cost Tracking [#cost-tracking]
```bash
# Pi agent costs
bitrouter costs breakdown --agent pi
# Set limits
bitrouter budget set --agent pi --daily 10.00
# Generate report
bitrouter report generate --agent pi --period week
```
Troubleshooting [#troubleshooting]
🔴 Connection Issues [#-connection-issues]
```bash
# Check BitRouter
curl http://localhost:8787/health
# Pi configuration
pi config show
# Test connection
pi debug connection --provider custom
```
🟡 Extension Problems [#-extension-problems]
```bash
# List extensions
pi extensions list
# Reload extensions
pi extensions reload
# Debug extension
pi debug extension bitrouter
```
🔵 Session Persistence [#-session-persistence]
```bash
# Check session storage
ls -la ~/.pi/sessions/
# Validate JSONL
pi session validate
# Clear corrupted
pi session clear --corrupted
```
Advanced Features [#advanced-features]
Sub-Agent Orchestration [#sub-agent-orchestration]
```typescript
export class SubAgentExtension extends Extension {
async createSubAgent(task) {
return {
name: `pi-sub-${task.id}`,
route: `pi/subagent/${task.type}/*`,
model: this.selectModelForTask(task)
};
}
}
```
Plan Mode Integration [#plan-mode-integration]
```yaml
plan_mode:
pi:
enabled: true
route: "pi/planning/*"
features:
- auto_planning
- step_validation
- progress_tracking
model_selection:
planning: claude-3-5-sonnet-latest
execution: gpt-4o
```
Learn More [#learn-more]
* 📚 [Pi Documentation](https://pi.dev/docs)
* 🔧 [GitHub Repository](https://github.com/earendil-works/pi)
* 📦 [Package Registry](https://npmjs.com/search?q=pi-coding-agent)
* 💬 [Discord Community](https://discord.gg/G3zVrZDa5C)
# 迁移指南 (/zh/docs/cookbook/migration)
迁移指南 [#迁移指南]
了解如何以最小的中断将您现有的 LLM 路由解决方案迁移到 BitRouter。
使用 Agent Skills 快速迁移 [#使用-agent-skills-快速迁移]
最快的迁移方式是让 Agent 代劳。Claude Code 中的 **BitRouter skill** 可以自动检测您当前的配置、更新 `baseURL` 和 API 密钥，并验证结果。
安装 agent skills 包：
```
npx skills add BitRouterAI/agent-skills
```
然后描述您正在从哪个方案迁移——例如：*"将我的 OpenRouter 配置迁移到 BitRouter"*。Agent 会完成剩余的工作。
通用迁移指南 [#通用迁移指南]
无论您当前使用哪个服务商，核心变更是一样的：将您现有的 OpenAI 兼容客户端指向 BitRouter，只需更新两个值。
1. 更新 Base URL [#1-更新-base-url]
```
# 云端
https://api.bitrouter.ai/v1
# 自托管
http://localhost:8787/v1
```
2. 更新 API 密钥 [#2-更新-api-密钥]
```bash
BITROUTER_API_KEY=your-key-here
```
将其设置为 Bearer Token（或 `api_key` 字段），替换当前服务商密钥所在的位置。
3. 模型名称保持不变 [#3-模型名称保持不变]
BitRouter 使用与 OpenAI 兼容 API 相同的模型 ID（`gpt-4o`、`claude-3-5-sonnet-20241022` 等）——无需重命名。
4. 验证切换结果 [#4-验证切换结果]
```bash
curl https://api.bitrouter.ai/v1/chat/completions \
-H "Authorization: Bearer $BITROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "你好"}]}'
```
如需针对特定服务商的详细步骤和边界情况处理，请参阅以下指南。
可用的迁移指南 [#可用的迁移指南]
从 OpenRouter 迁移 [#从-openrouter-迁移]
为使用 OpenRouter 的团队提供完整指南，帮助他们切换到 BitRouter，以获得更好的性能、自托管选项和原生代理功能。
从 LiteLLM 迁移 [#从-litellm-迁移]
从 LiteLLM 的 Python SDK 或代理服务器逐步迁移到 BitRouter 的高性能 Rust 二进制文件，无需任何依赖。
为什么迁移到 BitRouter？ [#为什么迁移到-bitrouter]
* **性能**：\<10ms 路由开销 vs 其他方案的 25-100ms
* **简单性**：单一二进制文件，无需数据库或容器
* **代理原生**：内置 MCP/ACP 网关、守护栏和技能库
* **灵活性**：自托管或云端，BYOK 或按需付费
* **开源**：Apache 2.0 许可证，无需许可使用
需要帮助？ [#需要帮助]
* 加入我们的 [Discord 社区](https://discord.gg/G3zVrZDa5C) 获取迁移支持
* 在 [GitHub 上提交问题](https://github.com/bitrouter/bitrouter/issues)
* 联系 [contact@bitrouter.ai](mailto:contact@bitrouter.ai) 获取企业迁移协助
# 从 LiteLLM 迁移 (/zh/docs/cookbook/migration/litellm)
import { Callout } from 'fumadocs-ui/components/callout';
import { Cards, Card } from 'fumadocs-ui/components/card';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
从 LiteLLM 迁移到 BitRouter [#从-litellm-迁移到-bitrouter]
LiteLLM 是用于统一访问 100+ LLM 提供商的 Python SDK 与自托管代理。BitRouter 从另一个角度解决同一问题：一个**面向 Agent 的代理**，提供单一 OpenAI 兼容接口 —— 既可作为本地二进制运行（BYOK，无需基础设施），也可通过托管端点支持 Agent 自主支付。本指南面向工作负载已从后端服务转向 Agent 运行时、希望使用更精简、Agent 优先接口的团队。
为什么要迁移？ [#为什么要迁移]
| | LiteLLM Proxy | BitRouter |
| --------------- | ------------------------------------- | -------------------------------------------------- |
| **运行时** | Python | Rust（单一静态二进制） |
| **生产依赖** | Postgres + Redis + Docker/K8s | 无 |
| **部署模式** | 仅自托管 | 本地二进制**或**托管（`cloud.bitrouter.ai`）—— OpenAI 兼容端点相同 |
| **Agent 身份与支付** | 无 | x402 / MPP 自主支付（云模式） |
| **设计重心** | 一体化 LLM 网关：管理 UI、虚拟密钥、预算，再附加 Agent 网关 | Agent 优先代理：MCP / ACP / 技能、Agent 防火墙、Agent 支付即核心接口 |
| **Agent 协议面** | MCP、A2A、Skills、CLI —— 附加在横向网关之上 | MCP、ACP、Skills、CLI —— 即产品本身，而非附加 |
| **许可证** | MIT（SDK）/ 付费企业版 | 全栈 Apache 2.0 |
两个值得强调的差异 [#两个值得强调的差异]
1. 云端与本地共享同一接口 [#1-云端与本地共享同一接口]
LiteLLM 的代理需要你自己运维。BitRouter 的**托管云与本地二进制对外暴露同一个 OpenAI 兼容端点** —— 开发期可在本地启动，生产期切换到 `cloud.bitrouter.ai`（反之亦然），客户端代码不需要修改。CLI、向导和 Agent Skills 在两种模式下都能使用；在设置 TUI 中按一个键即可切换。两种流程详见[快速开始](/docs/guides/overview/quickstart)。
当你希望 Agent *按请求付费*、而你无需为其分配密钥时，这一点尤其重要 —— 云模式支持 [x402 / MPP 自主支付](/docs/guides/features/payment)，LiteLLM 中没有对应能力。
2. Agent 原生，而非一体化 [#2-agent-原生而非一体化]
LiteLLM 已在其横向 LLM 网关之上推出 MCP、A2A、Skills 与 CLI —— 同时还附带虚拟密钥、团队预算、消费仪表板、管理 UI 一整套。BitRouter 反其道而行：Agent 原语*即*产品，团队管理那一套保持极简。BitRouter 接口暴露的能力：
* [MCP 网关](/docs/guides/features/mcp) —— 代理 MCP 服务器，让 Agent 跨主机发现工具。
* [ACP 网关](/docs/guides/features/acp) —— 一等支持 Claude Code、Codex、OpenCode 等使用的 Agent Client Protocol。
* [Guardrails](/docs/guides/features/guardrails) —— 代理跳点上的 Agent 防火墙：原位检查、脱敏或拦截。
* [Observability](/docs/guides/features/observability) —— 内置消费与请求追踪，无需外部收集器。
* Agent Skills 网关（即将推出）—— 按技能而非模型名称安装与路由能力。
* [Headless CLI](/docs/guides/features/cli) —— TUI 向导与可脚本化命令,用于配置与运维。
* [Agent 身份与支付](/docs/guides/features/payment) —— x402 / MPP,让 Agent 无需你为其分配密钥即可按请求付费。LiteLLM 中没有对应能力。
如果你依赖 LiteLLM 的团队管理 UI、虚拟密钥与按用户预算,LiteLLM 仍是更合适的选择。如果你在构建 Agent —— 尤其是需要自主支付的 Agent —— BitRouter 是更合适的选择。
迁移路径 [#迁移路径]
从 LiteLLM Python SDK 迁移 [#从-litellm-python-sdk-迁移]
LiteLLM 作为库的用法，可以在标准 OpenAI SDK 上换成 BitRouter 的 base URL：
```python
from litellm import completion
response = completion(
model="openai/gpt-4o",
messages=[{"role": "user", "content": "你好"}],
api_key="sk-...",
)
```
```python
import openai
# 本地：`bitrouter`（通过环境变量 BYOK）—— 见 /docs/guides/overview/quickstart
# 云端：base_url="https://cloud.bitrouter.ai/v1"，api_key=$BITROUTER_API_KEY
client = openai.OpenAI(
base_url="http://localhost:8787/v1",
api_key="not-used-in-local-byok",
)
response = client.chat.completions.create(
model="openai/gpt-4o",
messages=[{"role": "user", "content": "你好"}],
)
```
你以前用 `litellm.Router` 配置的回退与提供商选择，现在迁移到 BitRouter 的[路由预设](/docs/guides/features/presets)与[模型回退规则](/docs/guides/routing/model-fallback) —— 一次声明，而非每次调用都写。
从 LiteLLM Proxy 迁移 [#从-litellm-proxy-迁移]
代理迁移把 Python 进程 + Postgres + Redis 替换成一个二进制。安装并启动：
```bash
docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=pass postgres
docker run -d -p 6379:6379 redis
pip install 'litellm[proxy]'
litellm --config config.yaml --port 8000
```
```bash
# 安装方式（curl、npm、brew 或 cargo —— 详见快速开始）
curl -fsSL https://bitrouter.ai/install.sh | sh
# 设置提供商密钥；BitRouter 启动时自动识别
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
# 交互式向导（云或本地）；默认本地监听 :8787
bitrouter
```
如果你想完全跳过本地代理，可以直接让客户端指向 `https://cloud.bitrouter.ai/v1`，使用 BitRouter API 密钥 —— 无二进制，无基础设施，端点形态完全一致。
功能映射 [#功能映射]
| LiteLLM 概念 | BitRouter 等价物 | 文档 |
| -------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `config.yaml` 中的 `model_list` | 提供商密钥 + 路由预设 | [Presets](/docs/guides/features/presets) |
| `router_settings`（重试、回退） | 模型回退规则 | [Model fallback](/docs/guides/routing/model-fallback) |
| `routing_strategy`（least-busy、latency） | 提供商选择 | [Provider selection](/docs/guides/routing/provider-selection) |
| `cache`（Redis/DynamoDB 后端） | 代理内未内置 —— 如需，请在应用 / 边缘层处理 | — |
| 虚拟密钥 + 预算 + 管理 UI | Workspace 密钥（云）；环境变量密钥（本地） | [BYOK](/docs/guides/features/byok)、[Workspaces](/docs/guides/features/workspaces) |
| Guardrails / PII / 内容过滤 | 代理跳点上的 Agent 防火墙 | [Guardrails](/docs/guides/features/guardrails) |
| Callbacks（Langfuse、Datadog 等） | 内置消费与请求日志；导出钩子规划中 | [Observability](/docs/guides/features/observability) |
| MCP Gateway | MCP 网关 | [MCP](/docs/guides/features/mcp) |
| A2A Agent Gateway | ACP 网关 | [ACP](/docs/guides/features/acp) |
| Skills Gateway / `/skills` 端点 | Skills 网关 + [agentskills.io](https://agentskills.io) 注册表 | [Agent Skills](/docs/guides/features/agentskills) |
| LiteLLM Proxy CLI | `bitrouter` CLI / TUI | [Headless CLI](/docs/guides/features/cli) |
| —（无对应） | Agent 自主支付（x402 / MPP） | [Payment](/docs/guides/features/payment) |
BitRouter 有意未提供的能力 [#bitrouter-有意未提供的能力]
为了让预期更准确：BitRouter 没有内置可与 LiteLLM Enterprise 对齐的团队/用户预算管理 UI、API 化的虚拟密钥生成或消费分析仪表板。云模式下的 Workspace 密钥隔离与本地模式下的环境变量密钥能覆盖常见需求，但如果你的迁移依赖于在代理内部按用户配额执行的虚拟密钥，请提前规划这一缺口，或在这些工作负载上继续使用 LiteLLM。
迁移清单 [#迁移清单]
**迁移前**
* [ ] 列出你实际使用的提供商与模型（其余可跳过）
* [ ] 记录所有自定义 callback / 中间件 —— 看看是否有 [guardrail 规则](/docs/guides/features/guardrails)能覆盖
* [ ] 决定使用云、本地或两者（它们共享端点）
**迁移**
* [ ] 安装 BitRouter CLI（[快速开始](/docs/guides/overview/quickstart)）
* [ ] 导出提供商密钥，或在云端控制台粘贴（sealed-box 加密）
* [ ] 将客户端 `base_url` 更新为 `http://localhost:8787/v1`（本地）或 `https://cloud.bitrouter.ai/v1`（云）
* [ ] 发送示例请求进行验证
* [ ] 如本地方案足够，停用 Postgres / Redis
下一步 [#下一步]
获取帮助 [#获取帮助]
* **Discord**：[加入社区](https://discord.gg/G3zVrZDa5C)获取迁移支持
* **GitHub**：[提交 issue](https://github.com/bitrouter/bitrouter/issues)
* **邮件**：[contact@bitrouter.ai](mailto:contact@bitrouter.ai) 获取企业迁移支持
# 从 OpenRouter 迁移 (/zh/docs/cookbook/migration/openrouter)
import { Cards, Card } from 'fumadocs-ui/components/card';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
从 OpenRouter 迁移到 BitRouter [#从-openrouter-迁移到-bitrouter]
本指南将带您完成从现有 OpenRouter 集成迁移到 BitRouter 的过程，重点介绍关键差异和优势。
为什么要迁移？ [#为什么要迁移]
对于智能代理工作负载，BitRouter 相比 OpenRouter 提供了多项优势：
| 功能 | OpenRouter | BitRouter |
| --------- | ----------------- | ------------------------- |
| **部署方式** | 仅云端（闭源） | 自托管或云端（Apache 2.0） |
| **平台手续费** | 通过 Stripe 收取 5.5% | 稳定币 2% · Stripe 5% |
| **代理功能** | 基础路由 | 无界面 CLI、代理自主支付、MCP/ACP 网关 |
| **访问** | 需要注册账户 | 无需注册即可使用 |
迁移路径 [#迁移路径]
步骤 1：获取 BitRouter API 密钥 [#步骤-1获取-bitrouter-api-密钥]
**方式 A：无界面 CLI（推荐）**
安装 CLI 并登录——`bitrouter auth login` 通过 RFC 8628 设备码流程在浏览器中打开授权页，授权后会将 OAuth 凭证（自动续期）保存到 `$XDG_DATA_HOME/bitrouter/account-credentials.json`。此后通过 `bitrouter` provider 的每次请求都会自动携带凭证——无需在配置中写入 API 密钥：
```bash
npm install -g bitrouter
bitrouter auth login
```
使用 `bitrouter auth whoami` 查看本机会话；使用 `bitrouter cloud --help` 管理账户级资源（API 密钥、用量、计费、策略、BYOK、OAuth 客户端）。
**方式 B：控制台**
在 [cloud.bitrouter.ai](https://cloud.bitrouter.ai) 注册并从控制台复制您的 API 密钥。
步骤 2：更新 Base URL 和 API 密钥 [#步骤-2更新-base-url-和-api-密钥]
迁移就这两步。将 OpenRouter 的端点和密钥替换为 BitRouter 的：
```python
# 之前（OpenRouter）
client = openai.OpenAI(
base_url="https://openrouter.ai/api/v1",
api_key=OPENROUTER_API_KEY,
)
# 之后（BitRouter）
client = openai.OpenAI(
base_url="https://api.bitrouter.ai/v1",
api_key=BITROUTER_API_KEY,
)
```
```javascript
// 之前（OpenRouter）
const client = new OpenAI({
baseURL: 'https://openrouter.ai/api/v1',
apiKey: OPENROUTER_API_KEY,
});
// 之后（BitRouter）
const client = new OpenAI({
baseURL: 'https://api.bitrouter.ai/v1',
apiKey: BITROUTER_API_KEY,
});
```
```bash
# 之前（OpenRouter）
curl https://openrouter.ai/api/v1/chat/completions \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "openai/gpt-4o", "messages": [{"role": "user", "content": "你好"}]}'
# 之后（BitRouter）
curl https://api.bitrouter.ai/v1/chat/completions \
-H "Authorization: Bearer $BITROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "openai/gpt-4o", "messages": [{"role": "user", "content": "你好"}]}'
```
可移除的请求头 [#可移除的请求头]
如果您的 OpenRouter 集成中设置了以下请求头，可以安全删除：
| OpenRouter 请求头 | BitRouter 中的状态 |
| -------------- | ----------------- |
| `HTTP-Referer` | 不使用 |
| `X-Title` | 不使用 |
| `transforms` | 不使用——守护栏在服务端配置 |
| `route` | 不使用——提供商路由在控制台中配置 |
下一步 [#下一步]
需要帮助？ [#需要帮助]
* **Discord**：[加入我们的社区](https://discord.gg/G3zVrZDa5C) 获取迁移支持
* **GitHub**：[报告问题](https://github.com/bitrouter/bitrouter/issues) 或贡献代码
* **Email**：[contact@bitrouter.ai](mailto:contact@bitrouter.ai) 企业迁移协助
# Create message (/zh/docs/api-reference/anthropic-compatible/createMessage)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Creates a message using the Anthropic Messages API format. Drop-in replacement for the Anthropic API.
When `stream: true`, the response is sent as Server-Sent Events (SSE). Each event has a `type` field indicating the event kind (`message_start`, `content_block_delta`, `message_delta`, `message_stop`).
# Get BYOK sealed-box public key (/zh/docs/api-reference/byok/getEncryptionPubkey)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Returns the node's current X25519 sealed-box public key plus its `kek_id` fingerprint. The console encrypts the user's provider key against this pubkey before storing the ciphertext — the node never sees plaintext on the write path.
Honors `If-None-Match: ""` for cheap caching, returning `304 Not Modified` when the cached fingerprint still matches.
# List available models (/zh/docs/api-reference/discovery/listModels)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Returns all models available across configured providers. Supports optional query filters for provider, model ID substring, and modality.
# List providers (/zh/docs/api-reference/discovery/listProviders)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Public registry of providers the node knows about, sourced from the upstream `bitrouter-providers` builtins. Used by the console to render the BYOK page without hard-coding the list.
# Generate content (Google) (/zh/docs/api-reference/google-compatible/googleGenerateContent)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Generates content using the Google Generative Language API format. Drop-in replacement for `generativelanguage.googleapis.com/v1beta`.
The model id and streaming verb are both encoded in the `model_action` path segment — for example `gemini-2.0-flash:generateContent` (synchronous) or `gemini-2.0-flash:streamGenerateContent` (SSE). The cloud injects the model id into the request body before dispatching, so callers can use the same URL convention as Google's own API.
# Liveness check (/zh/docs/api-reference/health/ping)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Returns `200 OK` with an empty body if the node is up.
# Prometheus metrics scrape (/zh/docs/api-reference/observability/getMetrics)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Returns Prometheus-format metrics for ingestion by a scraper. Not intended for human callers — point Prometheus, Grafana Agent, or any OpenMetrics-compatible collector at this endpoint.
Responds `404 Not Found` when the node was built or configured without a metrics renderer; scrapers can use that as a feature probe.
# Bind a policy to a principal (/zh/docs/api-reference/management/bindPolicy)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Attaches the policy to a principal (account / api\_key / oauth\_token / oauth\_client). The engine sums all bindings most-restrictive-wins at request time.
*Requires the `policy:write` scope.*
# Create a Stripe Checkout Session (/zh/docs/api-reference/management/createCheckoutSession)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Creates a Stripe Checkout Session to buy credits. Returns the hosted URL the user must visit to complete payment.
*Requires the `billing:write` scope.*
# Create a policy (/zh/docs/api-reference/management/createPolicy)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Create a `budget` / `rate_limit` / `guardrail` / `preset` policy. The `spec` body must match the requested `kind`.
*Requires the `policy:write` scope.*
# Delete a BYOK provider key (/zh/docs/api-reference/management/deleteByokKey)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
*Requires the `byok:write` scope.*
# Delete an OAuth client (/zh/docs/api-reference/management/deleteOauthClient)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
*Requires the `clients:write` scope.*
# Delete a policy and its bindings (/zh/docs/api-reference/management/deletePolicy)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
*Requires the `policy:write` scope.*
# Credit account balance (/zh/docs/api-reference/management/getBillingBalance)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Returns the raw balance, pending debits, and effective available amount in micro-USD.
*Requires the `billing:read` scope.*
# Aggregate spend / tokens for a window (/zh/docs/api-reference/management/getUsageAggregate)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Sums `usage` / `pending_debit_recovery` ledger entries and the `requests` rows over the window. Defaults to the last 30 days.
*Requires the `usage:read` scope.*
# List API keys for the calling account (/zh/docs/api-reference/management/listApiKeys)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Account-scoped list of brk\_ API keys. Never returns the secret.
*Requires the `keys:read` scope.*
# List BYOK provider keys (/zh/docs/api-reference/management/listByokKeys)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Metadata-only — never returns the sealed ciphertext.
*Requires the `byok:read` scope.*
# List the caller's OAuth clients (/zh/docs/api-reference/management/listOauthClients)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Never returns the `client_secret_hash`.
*Requires the `clients:read` scope.*
# List account policies (/zh/docs/api-reference/management/listPolicies)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
*Requires the `policy:read` scope.*
# Paginated request history (/zh/docs/api-reference/management/listRequests)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Per-request metadata. Never includes the prompt or response body.
*Requires the `usage:read` scope.*
# Mint a new API key (/zh/docs/api-reference/management/mintApiKey)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Mint a brk\_ API key. Returns the plaintext token exactly once.
The requested `scopes` must be a subset of the caller's effective scopes — no upscaling (RFC 6749 §3.3).
*Requires the `keys:write` scope.*
# Register a new OAuth client (/zh/docs/api-reference/management/registerOauthClient)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Confidential clients receive the freshly minted `client_secret` once in the response — the cloud retains only the hash.
*Requires the `clients:write` scope.*
# Revoke an API key (/zh/docs/api-reference/management/revokeApiKey)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Stamps `revoked_at` on the row. Subsequent verifies fail with 401.
*Requires the `keys:write` scope.*
# Remove a policy binding (/zh/docs/api-reference/management/unbindPolicy)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
*Requires the `policy:write` scope.*
# Update an OAuth client (/zh/docs/api-reference/management/updateOauthClient)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Mutate the client's name, redirect URIs, allowed scopes, or allowed grant types. Each field is optional.
*Requires the `clients:write` scope.*
# Update a policy's name or spec (/zh/docs/api-reference/management/updatePolicy)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
In-place update of a policy's `name` and / or `spec`. Kind changes are not supported — recreate the policy if the kind needs to differ.
*Requires the `policy:write` scope.*
# Upsert a BYOK provider key (/zh/docs/api-reference/management/upsertByokKey)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Stores a sealed-box ciphertext for one provider. Refuses any payload sealed against a `kek_id` other than the cloud's current encryption pubkey (`/v1/byok/encryption-pubkey`).
*Requires the `byok:write` scope.*
# Create chat completion (/zh/docs/api-reference/openai-compatible/createChatCompletion)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Creates a chat completion for the given messages. Drop-in replacement for the OpenAI Chat Completions API — accepts the same request schema and returns the same response format, including `usage` with token counts.
The router resolves the requested model to an upstream provider, forwards the request, and returns the response. Supports both synchronous and streaming modes.
When `stream: true`, the response is sent as Server-Sent Events (SSE) where each `data` line contains a `ChatCompletionChunk` JSON object. The stream ends with `data: [DONE]`.
# Create response (/zh/docs/api-reference/openai-responses/createResponse)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Creates a response using the OpenAI Responses API format. Drop-in replacement for OpenAI's newer stateful-conversation surface.
When `stream: true`, the response is sent as Server-Sent Events (SSE) with the full output-item lifecycle (`response.created`, `response.output_item.added`, `response.output_text.delta`, `response.completed`, …). The cloud forwards the upstream provider's SSE stream unchanged.
# ACP gateway (/zh/docs/guides/features/acp)
{/* TODO: rule syntax, built-in classifiers, custom predicates, response actions. */}
# AgentSkills Gateway (/zh/docs/guides/features/agentskills)
{/* TODO: rule syntax, built-in classifiers, custom predicates, response actions. */}
# 添加外部密钥（BYOK） (/zh/docs/guides/features/byok)
import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
**BYOK**（Bring Your Own Key，自带密钥）让你的请求走你自己的供应商账号，而不是 BitRouter 的。你按上游的标价直接付费——BitRouter 不抽成、不加每 token 费用，且在云端写入路径上从不接触明文密钥。
按部署模式的不同，密钥流转方式也不同。
本地模式——环境变量自动检测 [#本地模式环境变量自动检测]
启动二进制、把供应商密钥设到环境里，就完事了。无需配置文件。
```bash
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export GOOGLE_API_KEY=AIza...
bitrouter
```
BitRouter 在启动时检测密钥，仅暴露当前已配置密钥的供应商。当某供应商的密钥缺失时，路由到该供应商的请求会返回 `402 Payment Required`，错误体里会指明缺失的环境变量名。
识别的环境变量 [#识别的环境变量]
| 供应商 | 推荐名 | 兼容名 |
| --------------- | --------------------------------- | --------------------------------- |
| OpenAI | `BITROUTER_OPENAI_API_KEY` | `OPENAI_API_KEY` |
| Anthropic | `BITROUTER_ANTHROPIC_API_KEY` | `ANTHROPIC_API_KEY` |
| Google | `BITROUTER_GOOGLE_API_KEY` | `GOOGLE_API_KEY`、`GEMINI_API_KEY` |
| 自定义（registry 内） | `BITROUTER__API_KEY` | — |
`BITROUTER_*` 名称的优先级高于兼容名——当你的 shell 已经为别的工具设置了 `OPENAI_API_KEY`，又想让 BitRouter 走另一个账号时很有用。
对于在 [registry](/docs/guides/overview/provider) 中以 `id: my-provider` 注册的自定义供应商，请设置 `BITROUTER_MY_PROVIDER_API_KEY`（全大写，连字符变下划线）。
**密钥可热更新。** BitRouter 监听父进程的环境；更新密钥后（重新 export 并 `kill -HUP $(pgrep bitrouter)`），下一次请求即生效，无需重启。
云端模式——Sealed-box 加密 [#云端模式sealed-box-加密]
在 `cloud.bitrouter.ai` 上，你的供应商密钥会在**客户端**用节点的 X25519 sealed-box 公钥加密之后再提交。节点在写入路径上从不看到明文；密文仅在请求时于内存中解密、且永不落日志。
流程如下：
1. **拉取节点公钥。** [`GET /v1/byok/encryption-pubkey`](/docs/api-reference/byok/getEncryptionPubkey) 返回当前的 X25519 公钥及其 `kek_id` 指纹。按指纹缓存，并以 `If-None-Match` 形式回传，可在密钥未变时直接拿到 `304 Not Modified`。
2. **用公钥加密明文密钥。** 使用 libsodium 的 `crypto_box_seal`（或任何 sealed-box 实现）。
3. **提交密文。** [console](https://cloud.bitrouter.ai) 在你粘贴密钥时，就在浏览器里完成第 1、2 步——你不需要离开 dashboard。同样的提交 API 也可用于脚本化的入网；详见 [API 参考](/docs/api-reference/byok/getEncryptionPubkey)。
加密示例 [#加密示例]
如果你用脚本提交密钥，下面是最小化的 sealed-box 步骤。其输出的密文就是提交端点期望的内容。
```js
import sodium from 'libsodium-wrappers';
await sodium.ready;
const meta = await fetch(
'https://cloud.bitrouter.ai/v1/byok/encryption-pubkey'
).then(r => r.json());
const ciphertext = sodium.crypto_box_seal(
sodium.from_string(process.env.OPENAI_API_KEY),
sodium.from_base64(meta.public_key, sodium.base64_variants.ORIGINAL)
);
const ciphertextB64 = sodium.to_base64(ciphertext, sodium.base64_variants.ORIGINAL);
// 提交 { provider: 'openai', kek_id: meta.kek_id, ciphertext: ciphertextB64 }
```
```python
import os, base64, requests
from nacl.public import PublicKey, SealedBox
meta = requests.get('https://cloud.bitrouter.ai/v1/byok/encryption-pubkey').json()
pubkey = PublicKey(base64.b64decode(meta['public_key']))
ciphertext = SealedBox(pubkey).encrypt(os.environ['OPENAI_API_KEY'].encode())
payload = {
'provider': 'openai',
'kek_id': meta['kek_id'],
'ciphertext': base64.b64encode(ciphertext).decode(),
}
# 将 `payload` POST 到 BYOK 提交端点。
```
```bash
META=$(curl -s https://cloud.bitrouter.ai/v1/byok/encryption-pubkey)
PUBKEY=$(echo "$META" | jq -r .public_key)
KEK_ID=$(echo "$META" | jq -r .kek_id)
CIPHERTEXT=$(printf '%s' "$OPENAI_API_KEY" \
| sodium-seal --pubkey "$PUBKEY" \
| base64)
# 提交 { provider: "openai", kek_id: "$KEK_ID", ciphertext: "$CIPHERTEXT" }
```
公钥端点支持 `If-None-Match` 缓存——把上一次响应中的 `kek_id` 钉住后回传，密钥未变时即可拿到 `304 Not Modified`。
密钥作用域 [#密钥作用域]
默认情况下，密钥的作用域是 [工作区](/docs/guides/features/workspaces)——工作区内的成员都可以发起经由这把密钥路由的请求，但任何人都无法读到密文或原始密钥。
若要做一次性覆盖，可以通过 `X-BitRouter-Key` 头把密钥附在单次请求上：
```bash
curl https://cloud.bitrouter.ai/v1/chat/completions \
-H "Authorization: Bearer $BITROUTER_TOKEN" \
-H "X-BitRouter-Key: openai=sk-..." \
-d '{...}'
```
**单次请求密钥以明文形式经 TLS 传输。** 云端节点解 TLS、在请求期间将密钥保留在内存里、随后丢弃——它不会被持久化。这对临时脚本和 CI 任务很方便，但若每次请求都同一把密钥，更建议走 sealed-box 上传通道：既更省（请求里不用每次带密钥字节），也更难因调试日志而泄漏。在本地模式下，回环跳的存在让明文头永不离开本机网络。
轮换、撤销与审计 [#轮换撤销与审计]
* **轮换** — 对同一供应商提交一份新密文即可，旧记录会原子性地被覆盖。
* **撤销** — 在 dashboard 里操作。使用旧密钥的在途请求会跑完；新请求开始返回 `402 Payment Required`。
* **审计** — 工作区的密钥历史视图记录了每一次提交的成员、时间和所用 `kek_id`。任何人——包括 BitRouter 运维——都不可见明文。
当节点的 `kek_id` 轮换时（每 90 天一次），已提交的密文会在内存中用前一个密钥重新封装；除非你显式选择，无需重新加密。
自定义供应商 [#自定义供应商]
只要 [registry](/docs/guides/overview/provider) 中的供应商在其 manifest 的 `payment.modes` 里声明了 `byok`，就可以走 BYOK。提交时使用的 provider 字段必须与 registry 里的 `id` 完全一致。本地模式的环境变量识别遵循 `BITROUTER__API_KEY` 约定。
# 无界面 CLI (/zh/docs/guides/features/cli)
import { Callout } from 'fumadocs-ui/components/callout';
`bitrouter` 是一个静态单文件二进制程序。除了守护进程控制命令（`serve`、`start`、`stop`、`status`）之外，v1 提供了两个面向云端的入口：`bitrouter auth …` 用于 OAuth 登录，`bitrouter cloud …` 用于登录后的所有账户操作。
登录 BitRouter Cloud [#登录-bitrouter-cloud]
`bitrouter auth login` 针对已配置的授权服务器执行 RFC 8628 设备授权流程，打印审批 URL，并将凭证持久化到 `$XDG_DATA_HOME/bitrouter/account-credentials.json`（Unix 上权限为 `0600`）。浏览器授权页面会让你选择将 CLI 绑定到哪个**工作区**——生成的凭证被烙入该工作区，此后所有 `bitrouter cloud` 命令都隐式指向它，无需任何 `--workspace` 参数。如需切换工作区，重新执行 `bitrouter auth login` 并选择目标工作区即可。访问令牌在过期前 60 秒内自动续期；续期不会改变工作区绑定。
```bash
bitrouter auth login
# 在浏览器中打开以下链接，选择要登录的工作区：
# https://cloud.bitrouter.ai/oauth/device?user_code=ABCD-EFGH
# Waiting for authorization (the code expires in 600s)…
```
默认授权服务器为 `https://api.bitrouter.ai`，可通过 `--oauth-as `（或 `BITROUTER_OAUTH_AS`）切换到自托管部署。默认 scope 集合覆盖推理及 keys、usage、billing-read、policy、BYOK、namespace-read 的读写——如需敏感 scope（`billing:write`、`user:write`、`clients:read`、`clients:write`），在登录时传入 `--scope "<现有> clients:write"`。
`bitrouter auth whoami` 直接读取本地凭证文件，不访问网络，同时打印已绑定的工作区。退出登录（尝试在 AS 端撤销并删除本地文件）使用 `bitrouter auth logout`。
执行 `bitrouter auth login` 之后，零配置模式会自动启用 `bitrouter` provider——账户内的每个可用模型都可作为 `bitrouter:` 路由，无需进一步配置。
管理账户：bitrouter cloud [#管理账户bitrouter-cloud]
每个叶子命令都支持 `--json` 输出原始响应；默认输出对单个资源采用 `systemctl` 风格的键值块，对列表采用紧凑表格。当服务器返回 `missing required scope: ` 的 403 时，CLI 会打印一条可直接粘贴的 `bitrouter auth login --scope "<现有> "` 提示。
凭证是\*\*工作区级（namespace-baked）\*\*的——密钥、用量、策略和 OAuth 客户端全部作用于登录时选择的工作区，`{nsid}` 路径段由 CLI 隐式解析。`billing` 和 `byok` 是用户级的，跨所有工作区生效。
bitrouter cloud whoami [#bitrouter-cloud-whoami]
本机存储的身份信息、已绑定的工作区，以及该 CLI 将访问的 `/v1/*` 基础 URL。离线读取。
bitrouter cloud namespace — 工作区 [#bitrouter-cloud-namespace--工作区]
查看你拥有的所有工作区及当前 CLI 会话所绑定的工作区。工作区的创建和删除是控制面操作，仅限 Console。
```bash
bitrouter cloud namespace list # 所有工作区，当前激活的标有 (active)
bitrouter cloud namespace current # 离线——读取本地凭证，无网络请求
```
若凭证早于工作区功能上线，`current` 会打印 `(no namespace — run \`bitrouter auth login\`)\`。
bitrouter cloud keys — API 密钥 [#bitrouter-cloud-keys--api-密钥]
管理当前工作区内的 `brk_` API 密钥。签发的密钥与调用方绑定到同一工作区，且无法超出调用方自身的 scope 范围。
```bash
bitrouter cloud keys list
bitrouter cloud keys mint --name ci --scope "policy:read usage:read"
bitrouter cloud keys revoke
```
`mint` 仅在响应中返回一次 `brk_…` 明文 token——服务器只保存其 SHA-256 哈希。请求的 scope 必须是当前生效 scope 的子集（RFC 6749 §3.3 禁止上调）。
bitrouter cloud usage / bitrouter cloud requests [#bitrouter-cloud-usage--bitrouter-cloud-requests]
```bash
bitrouter cloud usage # 最近 30 天
bitrouter cloud usage --from 2026-05-01T00:00:00Z --to 2026-06-01T00:00:00Z
bitrouter cloud requests --limit 50 --offset 0
```
`usage` 汇总当前工作区的花费（微美元）和 token 计数。`requests` 分页展示工作区维度的请求历史。
bitrouter cloud billing — 余额 + 充值 [#bitrouter-cloud-billing--余额--充值]
用户级——非工作区级；反映账号整体余额，与当前登录的工作区无关。
```bash
bitrouter cloud billing balance
bitrouter cloud billing checkout --amount-cents 2000 # 需要 billing:write
```
`checkout` 返回托管的 Stripe URL，需要 `billing:write` scope（不在默认集合中——请使用 `--scope` 重新登录）。
bitrouter cloud policy — 通用策略 CRUD [#bitrouter-cloud-policy--通用策略-crud]
```bash
bitrouter cloud policy list [--kind budget|rate-limit|guardrail|preset]
bitrouter cloud policy get
bitrouter cloud policy create --name nightly-cap --kind budget --spec spec.json
bitrouter cloud policy update [--name X] [--spec spec.json]
bitrouter cloud policy delete
bitrouter cloud policy bind --principal-type api_key --principal-id
bitrouter cloud policy unbind
bitrouter cloud policy disable
bitrouter cloud policy enable
bitrouter cloud policy bindings
bitrouter cloud policy effective --principal-type api_key --principal-id
bitrouter cloud policy for-principal api_key
```
`--spec` 读取 JSON 文件（或用 `-` 读取标准输入），内容为扁平的内层 spec 主体——例如 budget 的 `{"window": "day", "limit_micro_usd": 5000000}`。Principal 类型：`namespace`、`api_key`、`oauth_token`、`oauth_client`。`effective` 和 `for-principal` 会在不实际发起推理请求的情况下，回答"该 principal 的请求会被如何处理"。`disable` 暂存策略而不删除——引擎在请求时跳过已禁用的行。
bitrouter cloud budget / bitrouter cloud preset — 类型化简写 [#bitrouter-cloud-budget--bitrouter-cloud-preset--类型化简写]
针对 budget 类与 preset 类策略的扁平 wire shape：
```bash
bitrouter cloud budget create --name nightly-cap --window day --limit-micro-usd 5000000
bitrouter cloud preset create --name engineering --guardrail guardrail.json --budget budget.json
```
写入的数据库行与 `bitrouter cloud policy create --kind budget|preset` 完全相同——按调用方更方便的形式选用即可。
bitrouter cloud byok — BYOK provider 密钥 [#bitrouter-cloud-byok--byok-provider-密钥]
用户级——非工作区级；BYOK provider 密钥作用于账号整体。ciphertext 必须先用云端当前的 X25519 公钥封装——服务器只存储已加密的字节。封装前先通过 `GET /v1/byok/encryption-pubkey` 获取当前公钥。
```bash
bitrouter cloud byok list
bitrouter cloud byok set --provider anthropic \
--ciphertext-b64 --kek-id --key-prefix sk-ant-
bitrouter cloud byok delete
```
bitrouter cloud oauth-client — OAuth 客户端注册 [#bitrouter-cloud-oauth-client--oauth-客户端注册]
```bash
bitrouter cloud oauth-client list
bitrouter cloud oauth-client register \
--name "my-agent" --type confidential \
--grant authorization_code --grant refresh_token \
--scope inference:invoke --scope policy:read \
--redirect-uri https://my-agent.example.com/cb
bitrouter cloud oauth-client update --name "renamed"
bitrouter cloud oauth-client delete
```
需要 `clients:read` / `clients:write` scope，不在默认集合中。机密客户端新生成的 `client_secret` 仅在 `register` 响应中返回一次。
# 护栏 (/zh/docs/guides/features/guardrails)
{/* TODO: 规则语法、内置分类器、自定义谓词、响应动作。 */}
# MCP gateway (/zh/docs/guides/features/mcp)
{/* TODO: rule syntax, built-in classifiers, custom predicates, response actions. */}
# 可观测性 (/zh/docs/guides/features/observability)
{/* TODO: 追踪、指标端点、日志投递、CLI/TUI 演示。 */}
# Agentic Payment (/zh/docs/guides/features/payment)
{/* TODO: rule syntax, built-in classifiers, custom predicates, response actions. */}
# Presets (/zh/docs/guides/features/presets)
{/* TODO: rule syntax, built-in classifiers, custom predicates, response actions. */}
# 结构化输出（测试版） (/zh/docs/guides/features/structured-outputs)
import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
**测试版功能。** 结构化输出支持目前处于测试阶段。API 已稳定，但可能会根据用户反馈进行增强。请在 [GitHub](https://github.com/bitrouter/bitrouter/issues) 上报告任何问题或建议。
**结构化输出**确保模型响应符合您指定的 JSON 模式。BitRouter 提供统一的 API，无缝支持所有主要提供商 — 自动在各个提供商的原生格式之间进行转换。
快速开始 [#快速开始]
定义一次模式，随处使用。BitRouter 处理协议转换：
```typescript
import OpenAI from 'openai';
const client = new OpenAI({
baseURL: 'https://api.bitrouter.ai/v1',
apiKey: process.env.BITROUTER_API_KEY,
});
const completion = await client.chat.completions.create({
model: 'claude-3-5-sonnet-latest',
messages: [
{ role: 'user', content: '从这篇文章中提取关键事实...' }
],
response_format: {
type: 'json_schema',
json_schema: {
name: 'article_facts',
strict: true,
schema: {
type: 'object',
properties: {
title: { type: 'string' },
author: { type: 'string' },
key_points: {
type: 'array',
items: { type: 'string' }
},
sentiment: {
type: 'string',
enum: ['positive', 'neutral', 'negative']
}
},
required: ['title', 'key_points', 'sentiment']
}
}
}
});
// 响应保证匹配您的模式
const facts = JSON.parse(completion.choices[0].message.content);
```
```python
import anthropic
client = anthropic.Anthropic(
base_url="https://api.bitrouter.ai",
api_key=os.environ["BITROUTER_API_KEY"],
)
message = client.messages.create(
model="gpt-4o-2024-11-20",
messages=[
{"role": "user", "content": "从这篇文章中提取关键事实..."}
],
output_config={
"format": {
"type": "json_schema",
"schema": {
"type": "object",
"properties": {
"title": {"type": "string"},
"author": {"type": "string"},
"key_points": {
"type": "array",
"items": {"type": "string"}
},
"sentiment": {
"type": "string",
"enum": ["positive", "neutral", "negative"]
}
},
"required": ["title", "key_points", "sentiment"]
}
}
}
)
# 响应保证匹配您的模式
import json
facts = json.loads(message.content[0].text)
```
```bash
curl https://api.bitrouter.ai/v1/chat/completions \
-H "Authorization: Bearer $BITROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-2.0-flash-exp",
"messages": [
{"role": "user", "content": "从这篇文章中提取关键事实..."}
],
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "article_facts",
"strict": true,
"schema": {
"type": "object",
"properties": {
"title": {"type": "string"},
"author": {"type": "string"},
"key_points": {
"type": "array",
"items": {"type": "string"}
},
"sentiment": {
"type": "string",
"enum": ["positive", "neutral", "negative"]
}
},
"required": ["title", "key_points", "sentiment"]
}
}
}
}'
```
**协议自动检测。** BitRouter 自动检测您使用的协议（OpenAI Chat、Anthropic Messages 等）并将您的模式转换为提供商的原生格式。
工作原理 [#工作原理]
BitRouter 提供了一个跨所有提供商工作的统一 `response_format` 字段。当您发送请求时：
1. **入站解析** — BitRouter 检测您的客户端协议并提取模式
2. **跨协议路由** — 将模式转换为上游提供商的原生格式
3. **响应流式传输** — 通过标准 `TextDelta` 事件流式传输部分 JSON
4. **格式保留** — 响应保持您请求的协议形状
这意味着 OpenAI 客户端可以路由到 Anthropic，或者 Anthropic 客户端可以路由到 Google Gemini — 转换是自动进行的。
协议格式 [#协议格式]
每个提供商都有自己的原生结构化输出格式。BitRouter 在它们之间进行转换：
| 协议 | 原生格式 | BitRouter 接受 | 备注 |
| -------------------- | ----------------------------- | ------------------------------------- | ----------------------------- |
| **OpenAI Chat** | `response_format.json_schema` | 相同 | 完全支持 `name`、`strict`、`schema` |
| **OpenAI Responses** | `text.format` | 相同 | 保留兄弟键如 `text.verbosity` |
| **Anthropic** | `output_config.format` | 也支持旧版 `output_format` | 没有 `name` 或 `strict` 字段 |
| **Google Gemini** | `generationConfig` | `responseMimeType` + `responseSchema` | 仅模式，无 name/strict |
字段映射 [#字段映射]
在协议之间路由时，BitRouter 处理这些转换：
* **`name`** — OpenAI 必需，如果未提供则默认为 `"response"`。对于 Anthropic/Google 会被删除。
* **`strict`** — OpenAI 的严格模式标志。对于不支持它的提供商会被删除。
* **`schema`** — JSON Schema 本身。通过特定于提供商的调整传递。
**不执行验证。** BitRouter 是代理，而不是验证器。它将您的模式传递给提供商并按原样返回其响应。提供商负责模式执行。
高级用法 [#高级用法]
复杂嵌套模式 [#复杂嵌套模式]
结构化输出支持具有嵌套对象、数组和枚举的任意复杂 JSON 模式：
```typescript
const schema = {
type: 'object',
properties: {
analysis: {
type: 'object',
properties: {
entities: {
type: 'array',
items: {
type: 'object',
properties: {
name: { type: 'string' },
type: {
type: 'string',
enum: ['person', 'organization', 'location', 'event']
},
confidence: {
type: 'number',
minimum: 0,
maximum: 1
},
relationships: {
type: 'array',
items: {
type: 'object',
properties: {
target: { type: 'string' },
type: { type: 'string' }
},
required: ['target', 'type']
}
}
},
required: ['name', 'type', 'confidence']
}
},
summary: { type: 'string', maxLength: 500 },
topics: {
type: 'array',
items: { type: 'string' },
minItems: 1,
maxItems: 5
}
},
required: ['entities', 'summary', 'topics']
},
metadata: {
type: 'object',
properties: {
processed_at: { type: 'string', format: 'date-time' },
confidence_score: { type: 'number' }
},
required: ['processed_at']
}
},
required: ['analysis', 'metadata']
};
```
流式结构化输出 [#流式结构化输出]
结构化输出适用于流式响应。部分 JSON 作为文本增量流式传输回来：
```typescript
const stream = await client.chat.completions.create({
model: 'claude-3-5-sonnet-latest',
messages: [{ role: 'user', content: '分析此文档...' }],
response_format: {
type: 'json_schema',
json_schema: { name: 'analysis', schema: schema }
},
stream: true
});
let buffer = '';
for await (const chunk of stream) {
const delta = chunk.choices[0]?.delta?.content;
if (delta) {
buffer += delta;
// 部分 JSON 累积：{"analysis":{"entities":[{"name":"Acme Corp"...
}
}
const result = JSON.parse(buffer);
```
提供商特定注意事项 [#提供商特定注意事项]
OpenAI [#openai]
* 需要 `name` 字段（BitRouter 提供 `"response"` 作为默认值）
* 支持 `strict: true` 以实现更严格的模式执行
* 适用于 GPT-4o 模型（2024 年 11 月+）及更新版本
Anthropic [#anthropic]
* 通过 `output_config.format` 原生支持（不需要测试版标头）
* 不支持 `name` 或 `strict` 字段（BitRouter 会删除它们）
* 适用于 Claude 3.5 Sonnet 及更新版本
Google Gemini [#google-gemini]
* 使用 `generationConfig.responseMimeType: "application/json"`
* 模式放在 `generationConfig.responseSchema` 中
* 适用于 Gemini 1.5 Pro 和 Flash 模型
自定义提供商 [#自定义提供商]
在 BitRouter 的[提供商注册表](/docs/guides/overview/provider)中注册的任何提供商都可以通过我们的统一模式格式支持结构化输出。
限制 [#限制]
模型要求 [#模型要求]
BitRouter Cloud 上所有领先的智能体 LLM 都支持结构化输出，包括：
* **OpenAI**：GPT-4o、GPT-4o-mini、o1、o1-mini、o3-mini
* **Anthropic**：Claude 3.5 Sonnet、Claude 3.5 Haiku、Claude 3 Opus
* **Google**：Gemini 2.0 Flash、Gemini 1.5 Pro、Gemini 1.5 Flash
* **DeepSeek**：DeepSeek V3、DeepSeek R1
* **Meta**：Llama 3.3 70B、Llama 3.1 405B
* **其他**：大多数现代模型都支持 JSON 模式
模式约束 [#模式约束]
* 最大模式大小因提供商而异（通常为 10-50KB）
* 某些提供商限制嵌套深度（通常为 10-20 级）
* 某些 JSON Schema 功能可能不受支持（例如 `$ref`、`patternProperties`）
不支持 [#不支持]
* **响应验证** — BitRouter 不会根据模式验证响应
* **模式转换** — 输入必须是有效的 JSON Schema，不支持 TypeScript/Zod 等
* **旧版 JSON 模式** — 单独使用 `response_format: { type: "json_object" }`
**错误处理。** 如果模型不支持结构化输出，您将收到 `400 Bad Request` 以及有关不兼容的详细信息。如果模式无效，提供商将返回其特定的错误消息。
迁移指南 [#迁移指南]
如果您当前正在使用特定于提供商的结构化输出 API，以下是迁移方法：
从 OpenAI [#从-openai]
无需更改 — BitRouter 接受相同的格式：
```typescript
// 按原样工作
response_format: {
type: 'json_schema',
json_schema: { name: 'my_schema', strict: true, schema: {...} }
}
```
从 Anthropic [#从-anthropic]
更新为使用统一格式：
```python
# 之前（Anthropic 特定）
output_config={"format": {"type": "json_schema", "schema": {...}}}
# 之后（BitRouter 统一）
response_format={
"type": "json_schema",
"json_schema": {"schema": {...}} # name 和 strict 是可选的
}
```
从 Google Gemini [#从-google-gemini]
从拆分字段切换到统一格式：
```javascript
// 之前（Gemini 特定）
generationConfig: {
responseMimeType: 'application/json',
responseSchema: {...}
}
// 之后（BitRouter 统一）
response_format: {
type: 'json_schema',
json_schema: { schema: {...} }
}
```
另请参阅 [#另请参阅]
* [模型发现](/docs/api-reference/discovery/listModels) — 检查哪些模型支持结构化输出
* [提供商选择](/docs/guides/routing/provider-selection) — 路由到支持结构化输出的提供商
* [API 参考](/docs/api-reference) — 完整的 API 文档
# 工作区 (/zh/docs/guides/features/workspaces)
import { Callout } from 'fumadocs-ui/components/callout';
**工作区**是 BitRouter 的隔离边界。API 密钥、策略和使用数据全部作用于单个工作区。你可以拥有任意数量的工作区——按项目、环境或 Agent 部署各自创建一个即可。
凭证模型：用户级与工作区级 [#凭证模型用户级与工作区级]
每个凭证在签发时就确定了是**用户级（user-scoped）**还是**工作区级（workspace-scoped）**，签发后无法更改。
| | 用户级 | 工作区级 |
| ------------------- | ------------------- | ------------------------------ |
| **载体** | Console 网页会话（你的浏览器） | CLI 会话、API 密钥（`brk_`）、设备 token |
| **覆盖范围** | 你的所有工作区 + 账号级操作 | 仅限一个工作区 |
| **创建 / 删除工作区** | 是 | 否 |
| **管理账单** | 是 | 只读 |
| **管理工作区内的密钥、策略、用量** | 是 | 是 |
| **调用推理** | 仅限 Playground | 是 |
Console 网页会话是**唯一**的用户级凭证。没有任何长效的根凭证可跨工作区——这一权限刻意对 CLI 会话和 `brk_` 密钥关闭。
登录到工作区 [#登录到工作区]
`bitrouter auth login` 走 OAuth 设备授权流程。浏览器授权页面会让你选择将 CLI 绑定到哪个工作区。生成的凭证被烙入该工作区——此后所有 `bitrouter cloud` 命令都隐式指向它，无需任何 `--workspace` 参数。
```bash
bitrouter auth login
# 在浏览器中打开以下链接，选择要登录的工作区：
# https://cloud.bitrouter.ai/oauth/device?user_code=ABCD-EFGH
```
查看当前会话绑定到哪个工作区：
```bash
bitrouter cloud namespace current # 离线读取本地凭证
bitrouter auth whoami # 同时打印已绑定的工作区
```
若要切换到另一个工作区，重新执行 `bitrouter auth login` 并在浏览器中选择目标工作区即可，旧凭证会被覆盖。
```bash
bitrouter cloud namespace list # 你拥有的所有工作区，当前激活的标有 (active)
```
```
ns_01jxyz… default (active)
ns_01jabc… production
ns_01jdef… staging
```
完整的 `bitrouter cloud` 命令列表请参阅 [CLI 参考](/docs/guides/features/cli)。
Agent 在边界内的完全自治 [#agent-在边界内的完全自治]
登录后，CLI 会话（或从中签发的 `brk_` API 密钥）在其工作区内拥有完整的操作权：
**密钥管理** — 在工作区内创建、列出、撤销 API 密钥。从这里签发的任何密钥同样被烙入该工作区，继承相同边界。
```bash
bitrouter cloud keys mint --name my-agent \
--scope "inference:invoke keys:read policy:read usage:read"
bitrouter cloud keys list
bitrouter cloud keys revoke
```
**策略管理** — 读写护栏、限速和预设策略绑定。
```bash
bitrouter cloud policy list
bitrouter cloud policy bind --principal-type api_key --principal-id
bitrouter cloud budget create --name daily-cap --window day --limit-micro-usd 5000000
```
**用量查询** — 读取工作区维度的请求历史与消费数据。
```bash
bitrouter cloud usage
bitrouter cloud requests --limit 50
```
使用工作区级凭证的 Agent 或 CI 任务无法触及其他工作区、管理账单，也无法签发更宽泛的凭证。爆炸半径被严格限制在工作区内。
`bitrouter cloud keys mint` 是推荐 Agent 为其工具签发子密钥的方式。签发的密钥与调用方绑定到同一工作区，且无法超出调用方自身的 scope 范围。
管理工作区 [#管理工作区]
首次登录时系统会自动创建一个默认工作区。额外的工作区通过 Console 创建和删除——工作区生命周期属于控制面操作，需要用户级凭证（你的网页会话）。
CLI 仅支持列表操作：
```bash
bitrouter cloud namespace list # 你拥有的所有工作区
bitrouter cloud namespace current # 当前会话绑定的工作区（离线）
```
不能删除你的最后一个工作区——BitRouter 要求账号下至少保留一个工作区。
用量报告 [#用量报告]
工作区维度的请求归因在结算时完成，可通过 CLI 或 Console 查询：
```bash
bitrouter cloud usage # 最近 30 天
bitrouter cloud usage --from 2026-05-01T00:00:00Z --to 2026-06-01T00:00:00Z
bitrouter cloud requests --limit 25 # 分页请求日志
```
账号整体消费请参阅[账单](/docs/guides/features/payment)指南。工作区级消费上限正在规划中。
# 对比 (/zh/docs/guides/overview/comparison)
BitRouter 是唯一**专为 Agent 而生的智能路由器与开放市场**——开放（Apache 2.0、可本地部署、提供商注册与消费者使用均无许可）、智能（多提供商路由、可编程回退、运行时防护，路由开销低于 10ms）、Agent 原生（KYA 身份、自主 x402/MPP 支付、MCP/ACP 网关，以及为长时运行循环设计的可靠性原语）。
现有方案大致分为三类，没有任何一类同时覆盖以上三个属性。
vs 云端 SaaS 路由器（OpenRouter 等同类产品） [#vs-云端-saas-路由器openrouter-等同类产品]
云端 SaaS 路由器——以 **OpenRouter** 为代表——通过托管端点跨数百个模型路由请求，主要面向人工交互应用。
* **可自托管** — 云端 SaaS 路由器闭源、仅云端；BitRouter 采用 Apache 2.0，可作为单一二进制在任意环境运行。
* **无许可访问** — 这类服务需创建账户并使用信用卡或加密货币充值；BitRouter 托管服务使用 x402/Solana，无 KYC、无地域限制，Agent 按请求付费。
* **Agent 优先功能** — 云端 SaaS 路由器没有 Agent 防火墙、MCP/ACP 网关或技能注册中心；BitRouter 围绕这些功能构建。
* **更低延迟** — 路由开销低于 10ms，托管路由器通常约 25–40ms。
vs 自托管代理（LiteLLM 等同类产品） [#vs-自托管代理litellm-等同类产品]
自托管代理——以 **LiteLLM** 为代表——是常用于后端服务的开源 SDK 与 Python 代理。BYOK 模式，对基础设施依赖较重。
* **零运维** — 这类代理生产环境通常需要 Postgres、Redis 和 Docker/K8s；BitRouter 仅需一个二进制文件，无任何依赖。
* **性能** — 基于 Python 的代理在大规模并发时受 GIL 限制，尾延迟会下降；BitRouter 的 Rust 异步运行时延迟稳定。
* **支付** — 自托管代理仅支持 BYOK，不处理支付；BitRouter 托管服务支持自主 Agent 支付。
* **Agent 运行时** — 这类代理没有内联内容安全、KYA 身份或技能注册中心；BitRouter 都有。
vs 通用 API 网关（Portkey、Kong AI、AWS Bedrock Gateway 等） [#vs-通用-api-网关portkeykong-aiaws-bedrock-gateway-等]
通用 API 网关把 LLM 视作普通的上游 API，通常提供日志、缓存、限流、提供商故障转移、BYOK 计费和管理面板。
它们通常不提供：
* Agent 身份或运行时模型发现
* 自主支付协议（x402/MPP）
* MCP 或 ACP 网关功能
* Agent 能力的技能注册中心
* 亚 10ms 的原生二进制部署
这类网关适合传统的 API 运维场景。BitRouter 的存在是因为**自主 Agent 需要不同的接入面**——运行时模型选择、支付委托、内联安全，以及一套用于工具和子 Agent 发现的开放标准。
# 介绍 (/zh/docs/guides/overview)
什么是 BitRouter？ [#什么是-bitrouter]
BitRouter 是**面向 LLM Agent 的开放智能路由器**——一个开源、可本地部署、无前端的 Rust 二进制，为任意 Agent 提供统一端点，用以发现、路由并支付任意 LLM、工具或子 Agent。原生为自主 Agent 循环而生，具备一流的 CLI 运行时控制、可靠性、可观测性与防护；并作为一个无许可的市场与路由器运行——任意提供商可注册，任意消费者可使用。
功能 [#功能]
* **通用 LLM API** — 单一二进制，三套协议接口：OpenAI Chat Completions + Responses、Anthropic Messages、Google Generative AI。以你偏好的协议访问任意 LLM。
* **面向长时运行 Agent 的可靠性** — 自动重试、模型与提供商回退、连接复用、请求级幂等性，专为运行数小时乃至数天的 Agent 循环设计。
* **免费 BYOK** — 自带提供商密钥，零费用使用。BitRouter 自动从环境变量探测密钥——无需配置文件。
* **MCP & ACP 网关** — 代理 [MCP](https://modelcontextprotocol.io) 服务器，让 Agent 跨主机发现与调用工具。支持 [ACP](https://github.com/zed-industries/acp)，实现 Agent 身份、发现与任务分派。
* **运行时可观测性** — CLI + TUI 实时监控会话、请求、延迟与逐请求费用，并提供面向下游管道的结构化日志。
* **运行时防护** — 在代理层检查、警告、脱敏或拦截风险内容。无需任何应用层改动。
* **智能路由** — 多提供商路由，按成本与性能优化。跨协议路由（OpenAI ↔ Anthropic）、可编程回退、策略驱动的升级。
* **Agent 原生认证与支付** — KYA（Know-Your-Agent）身份与 x402/MPP 按使用付费的托管服务。Agent 自主认证与付款——无需信用卡、预充值或发票。
* **开放生态** — 无许可的[提供商注册](/docs/guides/overview/provider)。任何暴露 OpenAI 或 Anthropic 兼容端点的提供商，都可以加入网络并被网络上的 Agent 发现。
愿景 [#愿景]
为自主 Agent 构建一层开放、无许可的智能层——任何 Agent 都能在没有守门人的前提下，发现、支付并调用任何模型、工具或子 Agent。BitRouter 是其中的连接组织：开源、Agent 原生、由运营者掌控。
Agent 运行时 [#agent-运行时]
BitRouter 是任何支持自定义 OpenAI 或 Anthropic base URL 的运行时的即插即用代理——将其指向 `http://localhost:8787` 即可。
OpenClaw、Claude Code、ZeroClaw、Codex CLI、OpenCode、Kilo Code 等的接入方法详见 [Cookbook](/docs/cookbook)。
AI 资源 [#ai-资源]
可直接喂入 Agent 或 LLM 上下文的资源：
* **[`llms.txt`](https://bitrouter.ai/llms.txt)** — 精选的 BitRouter 文档索引，遵循 [llms.txt](https://llmstxt.org) 标准。
* **[`llms-full.txt`](https://bitrouter.ai/api/docs/llms-full.txt)** — 完整文档的纯文本版本，便于全量上下文摄取。
* **[Agent Skills](https://github.com/bitrouter/agent-skills)** — 为 Agent（Claude Code、Cursor、Copilot、Codex 等）即插即用的技能包，教 Agent 如何安装与使用 BitRouter。安装命令：`npx skills add BitRouterAI/agent-skills`。
* **[BitRouter CLI](https://github.com/bitrouter/bitrouter)** — `cargo install bitrouter` 即可安装。运行代理、交互式安装向导和 TUI 仪表盘。
* **[对比](/docs/guides/overview/comparison)** — BitRouter 与 OpenRouter、LiteLLM 及其他 API 网关的差异。
# 提供商接入 (/zh/docs/guides/overview/provider)
import { Callout } from 'fumadocs-ui/components/callout';
BitRouter Registry 目前处于**实验阶段**。在此期间，PR 会逐个审阅与合并，且我们保留拒绝或下架提供商的权利——详见下方[使用条款](#使用条款)。最终目标是完全无许可的接入流程；当前的审阅环节仅是为了在过渡期间维护网络的健康。
BitRouter 注册表 [#bitrouter-注册表]
BitRouter 被设计为一个面向推理的**开放市场**。任何运行 OpenAI 或 Anthropic 兼容推理端点的服务都可以申请注册——无需商业协议、无销售流程、无业务表单。
提供商列表存放于一个开源公共仓库：
> **[github.com/bitrouter/provider-registry](https://github.com/bitrouter/provider-registry)**
通过提交一份包含提供商清单（manifest）的 PR 即可申请注册。合并后，BitRouter 及网络上的任何 Agent 都能发现你的模型、向其路由请求，并通过 x402/MPP（可选）按请求付款。
注册流程 [#注册流程]
1. Fork [provider-registry](https://github.com/bitrouter/provider-registry)。
2. 在 `providers/.yaml` 添加一份清单，描述你的端点和模型目录。
3. 提交 PR。CI 会运行 schema 校验与基础可达性检查。
4. 维护者会审阅 PR。我们以开放接入为目标，但在实验阶段会逐个评估每个 PR。
5. 合并后，你的模型会在 BitRouter 网络与 bitrouter.ai 托管市场上变得可被发现。
**进入注册表 ≠ 一定有流量。** 注册表只是让你的模型可被发现，并不保证任何推理流量。BitRouter 运行一套独立的**路由系统**，持续监控、评分并排名所有提供商——详见下方[可靠性与路由](#可靠性与路由)。流量会流向得分较好的提供商；信号较弱的会被降权，与是否在注册表中无关。
提供商清单（Manifest） [#提供商清单manifest]
清单声明端点元数据、支付方式，以及 BitRouter 用于轮询的模型目录 URL。
```yaml
id: example-provider
name: Example AI
endpoint: https://api.example.ai/v1
protocol: openai # openai | anthropic
models_url: https://api.example.ai/v1/models
payment:
modes: [byok, x402]
x402_address: "0x..." # 可选，用于托管模式下的 Agent 支付
homepage: https://example.ai
support: https://example.ai/support
```
模型端点 [#模型端点]
BitRouter 会周期性地轮询你的 `models_url`，并按以下 schema 解析所有可用模型：
```json
{
"data": [
{
"id": "example/sonnet-1",
"name": "Example: Sonnet 1",
"created": 1704067200,
"input_modalities": ["text", "image"],
"output_modalities": ["text"],
"context_length": 1000000,
"max_output_length": 128000,
"quantization": "fp8",
"pricing": {
"prompt": "0.000003",
"completion": "0.000015",
"image": "0",
"request": "0",
"input_cache_read": "0"
},
"supported_sampling_parameters": ["temperature", "top_p", "stop"],
"supported_features": ["tools", "json_mode", "structured_outputs", "reasoning"],
"is_ready": true
}
]
}
```
关键字段：
* **`id`** — BitRouter 转发请求时使用的精确模型标识符。
* **`pricing`** — 每 token 的美元价格，使用字符串避免浮点精度问题。`image` 与 `request` 为单位价。
* **`is_ready`** — 设为 `false` 可在不上线的情况下暂存模型（适用于尚未发布的模型）。默认为 `true`。
合法 `quantization`：`int4`、`int8`、`fp4`、`fp6`、`fp8`、`fp16`、`bf16`、`fp32`。
合法 `supported_features`：`tools`、`json_mode`、`structured_outputs`、`logprobs`、`web_search`、`reasoning`。
合法 `supported_sampling_parameters`：`temperature`、`top_p`、`top_k`、`min_p`、`top_a`、`frequency_penalty`、`presence_penalty`、`repetition_penalty`、`stop`、`seed`、`max_tokens`、`logit_bias`。
分级定价 [#分级定价]
对于长上下文分级定价，可将 `pricing` 提供为数组。第一个条目为基础档位，后续条目在输入 token 数达到 `min_context` 时生效。
```json
{
"pricing": [
{ "prompt": "0.000002", "completion": "0.000012" },
{ "prompt": "0.000004", "completion": "0.000018", "min_context": 200000 }
]
}
```
弃用 [#弃用]
为计划下线的模型设置 `deprecation_date`（ISO 8601，`YYYY-MM-DD`）。BitRouter 会向消费者展示弃用提示，并可能在弃用日期后自动隐藏该模型。
可靠性与路由 [#可靠性与路由]
注册表告诉 BitRouter 你的端点上**有什么模型**，**路由系统**则决定向你发送多少流量——两者是独立的系统。
路由系统会持续监控每个端点的稳定性与性能，对所有提供商实时评分与排名。评分实时更新——若某个提供商的表现下滑，流量会在几分钟内迁移走。
**稳定性** — 成功请求数 ÷ 总请求数，扣除用户输入错误。
* 计入：`401`、`402`、`404`、`5xx`、流式中断错误、success-with-error-finish-reason。
* 不计入：`400`、`413`、`429`、`403`（单独追踪）。
**性能** — TTFT（首个 token 时间）与吞吐量（输出 token 数 ÷ 总生成时间，包含排队 + 取数 + 流式时间）。两者会公开展示在每个模型页面上。
要获得高分与流量：
* 过载时尽快返回 `429`，避免排队。
* token 一就绪即开始流式输出。
* 在生成 token 之前的长耗时阶段（如推理模型），通过 SSE 注释发送心跳，避免路由系统因超时而切换到回退提供商。
长期得分较差的提供商会被降权。滥用网络或违反下方[使用条款](#使用条款)的提供商会被直接下架。
支付 [#支付]
提供商可在清单中声明三种支付模式：
* **`byok`** — 消费者自带你服务的 API 密钥，BitRouter 不参与支付。
* **`x402`** — 接受 Agent 原生的 x402/MPP 按请求付款。BitRouter 将支付凭证转发到你清单中指定的地址。
* **`invoice`** — 为 BitRouter 聚合的托管模式流量启用发票账单。
新接入的提供商通常先开启 `byok` 与 `x402`，待流量增长后再启用 `invoice`。
更新你的列表 [#更新你的列表]
清单更新（新模型、价格变更、端点迁移）通过对 registry 提交 PR 完成。价格变更在合并后即时生效。要下线某个模型，可在下次模型端点轮询中将其设置为 `is_ready: false`，或提交 PR 删除该条目。
使用条款 [#使用条款]
注册成为提供商即表示你同意以下条款。违反条款将导致从注册表与托管市场中下架。
* **禁止有害内容** — 端点不得用于生成或明知协助生成 CSAM、大规模杀伤性武器相关知识、定向骚扰，或其他适用法律所禁止的内容。
* **禁止恶意行为** — 不得进行凭证窃取、对 Agent 的 prompt injection 攻击、响应篡改或隐蔽数据外泄。
* **元数据真实** — 清单与模型端点必须如实反映你的端点实际提供的内容：定价、上下文长度、能力、模态。元数据造假将导致立即下架。
* **合理可用性** — 长期未通过健康检查或对维护者沟通无回应的提供商，可能被下架。
* **合法运营** — 提供商应遵守其运营所在司法辖区的法律，包括相关的出口管制与制裁要求。
在实验阶段，我们保留以自身判断拒绝或下架任何提供商的权利。随着网络与工具链成熟，我们会将这一裁量权逐步收敛为客观、自动化的标准。
获取支持 [#获取支持]
* 在 [provider-registry](https://github.com/bitrouter/provider-registry/issues) 提交 Issue。
* 加入我们的 [Discord](https://discord.gg/G3zVrZDa5C)。
# 快速入门 (/zh/docs/guides/overview/quickstart)
import { Callout } from 'fumadocs-ui/components/callout';
import { Cards, Card } from 'fumadocs-ui/components/card';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
本指南将在一分钟内让 BitRouter 为你的 Agent 提供路由。BitRouter 有两种部署模式，每种模式都有两种接入方式：
* **BitRouter Cloud（默认）。** 托管端点 `cloud.bitrouter.ai`。无需管理密钥；支持 Agent 原生 x402/MPP 按请求付费，也可叠加 BYOK 使用。
* **本地代理。** 单一二进制运行于本机，BYOK 使用你自己的提供商密钥。零基础设施依赖。
两种模式都可通过 **Agent Skills**（让你的 Agent 自行安装与配置）或 **BitRouter CLI / TUI**（交互式向导）完成接入。两者均默认使用 Cloud；按一个键即可切换为本地模式。
Agent Skills [#agent-skills]
适用于支持 skills 的 Agent 运行时（Claude Code、Cursor、Codex、Copilot 等）。一次安装：
```bash
npx skills add BitRouterAI/agent-skills
```
然后告诉你的 Agent：*"帮我设置好 BitRouter。"*——Agent 会运行向导、默认选择 Cloud，并自动完成连接验证。
BitRouter CLI [#bitrouter-cli]
适用于命令行优先的接入。安装二进制：
```bash
curl -fsSL https://bitrouter.ai/install.sh | sh
```
```bash
npm install -g bitrouter
```
```bash
brew install bitrouter/tap/bitrouter
```
```bash
cargo install bitrouter
```
启动 TUI 向导：
```bash
bitrouter
```
向导会询问 **Cloud 还是本地？**（默认 Cloud），如果选择本地则提示输入密钥，随后在 `http://localhost:8787` 启动代理。
发送请求验证：
```bash
curl http://localhost:8787/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-4o",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
将任意 OpenAI 兼容的运行时指向 `http://localhost:8787/v1` 即可通过 BitRouter 路由。
下一步 [#下一步]
具体 Agent 运行时（Claude Code、OpenClaw、Codex CLI、OpenCode、Kilo Code 等）的接入方法详见 Cookbook。
# 模型回退 (/zh/docs/guides/routing/model-fallback)
import { Callout } from 'fumadocs-ui/components/callout';
LLM 上游会失败。限速、模型宕机、上下文溢出、内容过滤——这些原本会让代理循环卡住的错误，**模型回退** 让你在一次请求里传入一份有序的模型列表，BitRouter 会依次尝试，直到某个模型成功，并将那次成功的响应返回。
这是对 OpenAI、Anthropic、Google 三种协议表面在请求体层面的扩展。无需 SDK——只需设置一个字段。
快速示例 [#快速示例]
```bash
curl http://localhost:8787/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-4o",
"models": [
"openai/gpt-4o",
"anthropic/claude-sonnet-4-6",
"google/gemini-2.5-pro"
],
"messages": [{"role": "user", "content": "用一句话概括《伊利亚特》。"}]
}'
```
`model` 字段仍是计费与路由的主模型。`models` 数组以一个有序的优先级列表覆盖它——第一个成功返回的模型胜出。
**当 `models` 已设置时，可以省略 `model`。** 若两者同时存在，`models` 的第一项被视为主模型，`model` 被忽略。建议始终传入 `model`，让你应用里的错误日志保持可读。
触发回退的错误 [#触发回退的错误]
对于**上游侧、可能瞬时**的错误，BitRouter 会顺势尝试下一个模型；对由请求本身引起的 4xx 错误则直接返回给调用方。
| 情形 | 信号 | 行为 |
| ------------------ | ---------------- | ------------------ |
| 触发限速 | `429` | 回退 |
| 服务端错误 | `5xx` | 回退 |
| 超时 / 连接中断 | `408`、网络错误 | 回退 |
| 超出上下文窗口 | 各上游特定错误码 | 回退 |
| 内容过滤 / 拒答 | 各上游特定错误码 | 回退 |
| 流中失败（尚未输出 token） | 在首个 token 之前流被中断 | 回退 |
| 流中失败（已输出 token 之后） | 响应过程中流被中断 | **直接返回**——已有部分输出发出 |
| 鉴权错误 | `401` | 直接返回 |
| 余额不足 / 配额耗尽 | `402`、`403` | 直接返回 |
| 校验 / 请求格式错误 | `400`、`422` | 直接返回 |
| 客户端主动取消 | 客户端断开 | 直接返回 |
回退仅遍历一遍。BitRouter 按顺序对每个模型最多尝试一次，且回退之间不做指数退避——前提是：与其在失败的模型上等待，不如立刻切换到另一个模型。
**回退以请求为粒度，而非以 token 为粒度。** 如果模型 A 已成功回流到第 50 个 token 后断开，BitRouter 不会悄悄在模型 B 上重启——那会输出一段不连续的响应。请把回退作用在请求边界上；在你的代理里做检查点和续传，以获得流级别的容错。
查看是哪个模型应答的 [#查看是哪个模型应答的]
三条线索：
* **响应体的 `model` 字段** — 设置为实际生成响应的模型，而不是你最初请求的那个（OpenAI 约定）。
* **响应头 `bitrouter-served-by`** — `/`，例如 `anthropic-direct/anthropic/claude-sonnet-4-6`。
* **响应头 `bitrouter-fallback-trace`** — 以逗号分隔的尝试与结果列表，例如 `openai/gpt-4o:rate_limit,anthropic/claude-sonnet-4-6:served`。仅在至少触发了一次回退时输出。
成本与延迟权衡 [#成本与延迟权衡]
每次回退都是一次新的上游请求。实操建议：
* 期望最低成本：把 **最便宜的放最前**，接受高负载下尾延迟变差。
* 期望最低延迟：把 **最稳的放最前**，接受单 token 价更高。
* 长时间运行的代理循环：偏向稳定。一次卡住的代理循环带来的代价，远高于两个前沿模型之间那点边际单价差。
如果想跨「同一个模型的不同上游」声明式地优化成本或延迟，参见 [供应商选择](/docs/guides/routing/provider-selection)。回退与供应商选择是叠加的：BitRouter 先按你设置的策略为 `models` 中的每个模型挑选最佳上游，仅当当前模型上的上游重试预算耗尽时，才回退到列表中的下一个模型。
Anthropic 与 Google 协议表面 [#anthropic-与-google-协议表面]
`models` 字段在 `/v1/messages`（Anthropic Messages）与 `/v1beta/models/{model}:generateContent`（Google Generative AI）上行为一致。在 Anthropic 上，与既有的 `model` 字段一同读取；在 Google 上，BitRouter 将其作为请求体扩展接受——每次尝试时上游的 `:generateContent` 路径会被相应改写。
限制 [#限制]
* `models` 最多 8 项。
* 每个模型 ID 必须能在 [registry](/docs/guides/overview/provider) 中解析到一个已注册的模型。未识别的 ID 会在任何上游尝试之前返回 `400`。
* 支持流式。第一个开始输出 token 的模型胜出；即使其后流出现失败，也不会再尝试后续模型。
# Model Variants (/zh/docs/guides/routing/model-variants)
# 供应商选择 (/zh/docs/guides/routing/provider-selection)
import { Callout } from 'fumadocs-ui/components/callout';
BitRouter 上多数模型都由多个供应商承载。当你请求 `openai/gpt-4o` 时，BitRouter 必须挑选一个已注册的上游来发送请求。默认会用一个综合评分；通过 `provider.sort` 字段，你可以显式选择策略。
策略只有三种。哪个对当前请求最重要，就选哪个。
三种策略 [#三种策略]
| 策略 | 优化目标 | Tie-break |
| ------------ | ----------------------------------------------------- | ------------------------- |
| `price` | 最低单次请求成本，按你的 prompt 与预期 completion token 数、按上游当前定价计算。 | 更高在线率 → 更低错误率 → 供应商 ID。 |
| `latency` | 最近 1 小时滑动窗口内观测到的最低 p50 TTFT（首 token 时延）。 | 更高吞吐 → 更高在线率 → 供应商 ID。 |
| `throughput` | 最近 1 小时滑动窗口内观测到的最高输出 tokens/秒。 | 更低 TTFT → 更高在线率 → 供应商 ID。 |
遥测数据每分钟刷新一次。同样的数据可以在 registry 中各模型的页面上查看。
快速示例 [#快速示例]
```bash
curl http://localhost:8787/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-4o",
"provider": { "sort": "latency" },
"messages": [{"role": "user", "content": "把 Hello 翻译成法语。"}]
}'
```
同一个 `provider.sort` 字段在 `/v1/messages`（Anthropic）和 `/v1beta/models/{model}:generateContent`（Google）上行为一致。
BYOK 供应商优先 [#byok-供应商优先]
如果你已为某个供应商 [添加了外部密钥](/docs/guides/features/byok)，那么只要该供应商能承载某个模型，BitRouter 就会优先选它——排在所有非 BYOK 供应商之前，且不受 `provider.sort` 影响。BYOK 请求按上游标价直接计入你自己的账号、没有抽成；而且你已经显式选择了这家供应商，让默认行为尊重这个选择，是唯一不会让你后续被意外打到的策略。
在所有 BYOK 候选之中，`provider.sort` 策略照常生效。因此 `provider.sort: "latency"` 配合为 OpenAI 与 Anthropic 配置的 BYOK 密钥时，BitRouter 会先按 TTFT 在这两家之间排序；只有当两条 BYOK 通路都失败，才会按延迟向非 BYOK 供应商兜底。
在 **本地模式** 下，本节是空操作——所有供应商按定义都是 BYOK。
默认行为 [#默认行为]
未设置 `provider` 时，BitRouter 按**综合评分**排序——价格、延迟、吞吐与在线率的加权组合，并过滤掉在线率过低的供应商。这是大多数代理的合适默认；只有当某一个维度显著重要时，才需要显式设置策略。
**默认行为在不同版本之间不保持稳定。** 综合评分的权重会随我们对真实流量的观察而调整。如果你需要一个稳定、可复现的策略——用于成本核算、SLO 跟踪或 A/B 实验——请显式设置 `provider.sort`。
与回退如何叠加 [#与回退如何叠加]
[模型回退](/docs/guides/routing/model-fallback) 与供应商选择是两层独立机制：
1. 对 `models` 列表中的每个模型（或没有回退时只有 `model`），BitRouter 都按你设置的 `provider.sort` 策略挑选最佳上游。
2. 若所选上游遇到不会向调用方暴露的失败（限速、5xx），BitRouter 会先在**同一模型的下一名上游**重试，再切换到列表中的下一个模型。
3. 同一个 `provider.sort` 策略作用于回退列表中的每一个模型——不能为不同模型分别指定不同策略。
具体来说：`models: ["openai/gpt-4o", "anthropic/claude-sonnet-4-6"]` 配合 `provider.sort: "price"`，会先评估 GPT-4o 中最便宜的上游，再评估 Sonnet 中最便宜的上游，再返回错误。
指标打平时 [#指标打平时]
如果两家供应商对同一个 prompt 报价完全相同，那么在线率更高的胜出；若在线率也打平，则错误率更低的胜出；若一切都打平，BitRouter 按供应商 ID 字典序排序——确定且便于审计，但**不会做负载均衡**。如果在打平的供应商间均匀分发流量对你的工作负载很重要，请到 [Discord](https://discord.gg/G3zVrZDa5C) 描述用例；若有需求，我们会增加 `provider.balance` 旋钮。
没在这里的 [#没在这里的]
OpenRouter 暴露了大得多的旋钮面——`provider.order`、`provider.allow_fallbacks`、`provider.require_parameters`、`provider.data_collection`、`provider.ignore`、`provider.quantizations`，等等。在使用情况告诉我们需要更多之前，我们刻意只保留这一个旋钮、三个取值。如果你正从 OpenRouter 迁移过来，两条等价表达：
* **绑定到某一家供应商** — 直接使用带供应商前缀的模型 ID，例如 `model: "anthropic-direct/anthropic/claude-sonnet-4-6"`。
* **排除某一家供应商** — 在工作区的 registry 白名单里去掉它，而非放到请求体里。
如果缺失的旋钮挡住了你的真实工作负载，请到 [bitrouter](https://github.com/bitrouter/bitrouter) 提 issue。
# Router Variants (/zh/docs/guides/routing/router-variants)