convez.ai
AgenteIntegração & APIsIntermediário
ImBIOS

Relay — Proxy Universal de APIs de IA

ImBIOS/relay

Proxy universal que troca provedores de IA sem reiniciar seu agent

Ver no GitHub
BomPluginScore · de 0 a 100

Agent que funciona como proxy HTTP inteligente para trocar entre provedores de LLM (OpenAI, Anthropic, GitHub Copilot, DeepSeek, Groq, Ollama e mais) sem reiniciar sessões. Traduz protocolos automaticamente e permite hot-switching de provedores em tempo real, com suporte a múltiplas contas e rastreamento de quotas.

Instalação

$npx convez-ai ImBIOS/relay

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
10
Forks
0
Acompanhando
0
Saúde
100%
Último commit
há 4 meses
Versão
—
Issues abertas
2
Contribuidores
1

Casos de uso

  • Trocar entre diferentes provedores de LLM sem interromper o workflow
  • Rodar múltiplas contas por provedor com auto-rotação quando quotas expiram
  • Usar agentes de coding (Cline, Aider, Continue) com qualquer provedor
  • Traduzir automaticamente entre protocolos Anthropic e OpenAI

Veredito

Ferramenta técnica sólida para flexibilizar arquiteturas de AI coding, especialmente útil em ambientes multi-provedor ou experimentação. Reduz fricção operacional, mas requer configuração e compreensão de protocolos de API.

README

A tradução para o português deste README ainda está na fila.

Relay — Universal AI API Proxy

Bun GitHub

A CLI for managing and hot-switching LLM providers with a built-in HTTP proxy. Works with any AI coding agent (Claude Code, ForgeCode, OpenAI Codex CLI, OpenCode, Cline, Aider, Continue, etc.) and any provider that speaks the Anthropic or OpenAI API.

Supported Providers

ProviderProtocolModel SourceAuth
GitHub CopilotOpenAIDynamic (/models)OAuth / PAT
OpenAIOpenAIDynamic (/v1/models)API key
AnthropicAnthropicDynamicAPI key
Z.AI (GLM)AnthropicStatic (13 models)API key
MiniMaxAnthropicStatic (7 models)API key
OpenRouterOpenAIDynamicAPI key
Google AI StudioOpenAIStatic (7 models)API key
GroqOpenAIDynamicAPI key
CerebrasOpenAIDynamicAPI key
xAI (Grok)OpenAIDynamicAPI key
DeepSeekOpenAIDynamicAPI key
OllamaOpenAIDynamic (local)None
OpenAI-CompatibleOpenAIUser-definedAPI key
Anthropic-CompatibleAnthropicUser-definedAPI key

Adding a new provider only requires an entry in the provider registry — no code changes needed.

Why Relay?

AI coding agents cache the model name and base URL at session start. Swapping providers mid-session requires a full restart. With relay proxy, you point your agent at a local proxy once and hot-switch providers at any time without restarting.

Key features:

  • Agent-agnostic — works with any tool that speaks Anthropic or OpenAI protocol
  • Provider-agnostic — transparently routes to 14+ providers with automatic protocol translation
  • Hot-switch providers — change between Copilot, OpenAI, Anthropic, Z.AI, or any supported provider without restarting your session
  • Auto-rotation — automatically cycle through accounts when quotas are exhausted
  • Protocol translation — transparent Anthropic-to-OpenAI translation so agents speaking one protocol can use providers speaking the other
  • Usage tracking — real-time quota monitoring with percentage used and reset timers
  • Dynamic model discovery — fetch available models from provider APIs, with user-overridable model lists
  • Multi-account — add multiple accounts per provider, switch freely

Installation

From GitHub

# Install from main branch — requires git and pnpm
pnpm install -g github:ImBIOS/relay

Option A: Non-interactive (Docker/CI)

# Add accounts with API keys
relay account add --name "user@z.ai" --provider zai --key sk-xxx --activate
relay account add --name "user@minimax.com" --provider minimax --key mmkey-xxx

# Or use relay init for guided onboarding
relay init --providers zai,minimax --zai-api-key sk-xxx --minimax-api-key mmkey-xxx --install-hooks

# Start proxy
relay proxy status   # auto-starts if not running

Option B: GitHub Copilot via OAuth

# Interactive OAuth device flow — opens browser for authentication
relay account login copilot

# Or add with a fine-grained PAT
relay account add --name "you@github.com" --provider copilot --key github_pat_xxx

Option C: Run from source

git clone https://github.com/ImBIOS/relay.git
cd relay
bun install
bun src/run.ts account add   # interactive
bun src/run.ts proxy status

Configuration

Relay exposes a local proxy that any AI agent can connect to. Point your agent at http://127.0.0.1:8787/api/anthropic with any auth token (e.g. relay).

Claude Code

relay init --install-hooks writes the required environment and installs a SessionStart hook automatically.

To configure manually, add to ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "relay",
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8787/api/anthropic"
  }
}

ForgeCode

Add to .forge.toml:

[anthropic]
api_key = "relay"
base_url = "http://127.0.0.1:8787/api/anthropic"

Or use the shell wrapper:

relay hooks forge-setup     # Install wrapper + config
relay hooks forge-setup --uninstall  # Remove

OpenAI Codex CLI

Install the shell wrapper and config:

relay hooks codex-setup     # Install wrapper + ~/.codex/config.toml
relay hooks codex-setup --uninstall  # Remove

After setup, just run codex as usual — Relay handles the rest:

  • Sets OPENAI_API_KEY and OPENAI_BASE_URL to route through the proxy
  • Starts proxy and rotates accounts on launch
  • Configures ~/.codex/config.toml with the right model and provider

To configure manually, set environment variables:

export OPENAI_API_KEY="relay"
export OPENAI_BASE_URL="http://127.0.0.1:8787/api/openai/v1"
codex

OpenCode

Add to opencode.json:

{
  "provider": {
    "anthropic": {
      "apiKey": "relay",
      "baseURL": "http://127.0.0.1:8787/api/anthropic"
    }
  }
}

Any Agent

Any tool that supports custom Anthropic or OpenAI base URLs can use Relay. Set the base URL to http://127.0.0.1:8787/api/anthropic (for Anthropic-protocol agents like Claude Code, ForgeCode) or http://127.0.0.1:8787/api/openai/v1 (for OpenAI-protocol agents like Codex CLI) and use any string as the API key.

Commands

Proxy

CommandDescription
relay proxy startStart proxy on port 8787
relay proxy stopStop the proxy
relay proxy statusShow status and recent request log

Account Management

CommandDescription
relay account listList all configured accounts
relay account addAdd a new account (interactive or with flags)
relay account switch <ref>Switch by account id, name, or provider
relay account edit <id>Edit account name, API key, OAuth token
relay account remove <id>Remove an account
relay account login copilotLogin to GitHub Copilot via OAuth device flow
relay account migrateMigrate legacy configs to accounts system

Models

CommandDescription
relay modelsList models for all providers
relay models --provider copilotShow models for a specific provider
relay models refreshFetch latest models from provider APIs
relay models refresh --provider copilotRefresh a specific provider
relay models add --provider zai --id glm-6 --name "GLM-6"Add a custom model
relay models remove --provider zai --id glm-4.3Remove a custom model
relay models reset --provider zaiReset to built-in defaults

Monitoring

CommandDescription
relay usageShow usage for active account
relay usage --allShow usage for all accounts
relay usage --jsonJSON output for scripting
relay doctorDiagnose configuration issues
relay analyticsShow telemetry summary

Auto-Rotation

CommandDescription
relay auto enableEnable automatic account rotation
relay auto disableDisable auto-rotation
relay auto statusShow rotation status

How It Works

Any AI Agent
(Claude Code, ForgeCode, OpenAI Codex CLI, OpenCode, Cline, Aider, Continue, ...)
        │
        │  POST /api/anthropic/v1/messages  (or /api/openai/v1/chat/completions)
        │  (Authorization: Bearer relay)
        │
  ┌─────▼──────┐
  │ relay proxy │
  │             │
  │  • Auth: replaces token with real API key
  │  • Routing: sends to active provider
  │  • Translation: Anthropic ↔ OpenAI as needed
  │  • Passthrough: OpenAI → OpenAI (Codex CLI)
  │  • Logging: timestamp, model, provider, latency
  └─────┬──────┘
        │
   ┌────┼────────────────┐
   │    │                │
   ▼    ▼                ▼
Z.AI  MiniMax    GitHub Copilot
       │          │
       ▼          ▼
    OpenAI    OpenRouter
    Anthropic  DeepSeek
    Groq       Ollama
    ...        ...

Routing and translation: The proxy routes requests based on the active account's provider. For providers that speak Anthropic protocol (Z.AI, MiniMax, Anthropic), requests pass through directly. For OpenAI-protocol providers (Copilot, OpenAI, DeepSeek, Groq, etc.), the proxy translates between Anthropic and OpenAI wire formats transparently — so any agent can talk to any provider. Requests arriving at /api/openai (from tools like Codex CLI) are forwarded as-is to OpenAI-protocol providers without translation.

Model Management

Relay supports three sources of model definitions, resolved in priority order:

  1. User overrides — custom models added via relay models add
  2. Cached fetch — models fetched from provider APIs via relay models refresh (cached for 7 days)
  3. Built-in static — hardcoded defaults from the provider registry

This means you can always stay current:

  • Run relay models refresh to fetch the latest models from providers that support it
  • Add custom models with relay models add if a provider releases a new model before Relay is updated
  • Reset to defaults with relay models reset at any time

Usage Tracking

Relay fetches real usage data from providers that expose quota APIs:

  • GitHub Copilot: Premium interactions, chat, and completions quotas via copilot_internal/user
  • Z.AI: Token limits (daily and weekly) with reset timers
  • MiniMax: Token usage with quota tracking
$ relay usage

  github-copilot@ImBIOS — GitHub Copilot
  Plan: individual
  Premium Interactions: 67 / 300 (22.4% used)
  Resets at 07:00 on 1 Jun (397h left)

Notes for Docker and CI

  • relay account add --name ... --provider ... --key ... is safe for non-interactive environments
  • relay init --providers ... --install-hooks sets up everything in one command
  • Interactive flows (relay account add, relay account login copilot) require a TTY
  • relay account switch <provider> works when the provider resolves to exactly one account

Tech Stack

  • Runtime: Bun 1.2.0+
  • Language: TypeScript (ESM, strict)
  • CLI Framework: oclif + Ink (React-based terminal UI)
  • Linting: oxlint + oxfmt (OXC)
  • Testing: Bun test runner

Repo Structure

relay/
├── src/
│   ├── commands/
│   │   ├── account/       # add, list, switch, edit, remove, login, migrate
│   │   ├── proxy/         # start, stop, status
│   │   ├── auto/          # enable, disable, status
│   │   ├── hooks/         # session-start, forge-setup, codex-setup, install
│   │   ├── models.tsx     # list, add, remove, refresh, reset
│   │   ├── usage.tsx      # usage tracking
│   │   └── doctor.tsx     # diagnostics
│   ├── config/
│   │   ├── accounts-config.ts     # account management
│   │   ├── provider-registry.ts   # 14 provider definitions
│   │   ├── provider-metadata.ts   # provider metadata helpers
│   │   ├── models-cache.ts        # user-overridable model storage
│   │   └── settings.ts            # legacy config compat
│   ├── proxy/
│   │   ├── server.ts              # HTTP proxy with protocol translation
│   │   └── translators/
│   │       └── anthropic-openai.ts # Anthropic ↔ OpenAI translation
│   ├── providers/
│   │   ├── base.ts        # provider interface
│   │   ├── zai.ts         # Z.AI provider
│   │   ├── minimax.ts     # MiniMax provider
│   │   └── copilot.ts     # GitHub Copilot provider
│   └── utils/             # logger, telemetry, format, validation
└── bin/relay.bundled.js   # optional bundled build

License

See LICENSE

Ver o original no GitHub

Bom para

Relacionados