Claves del gateway y connect

Bóveda local opcional para asientos con API key: rotación y failover. Los asientos con plan/login (Cursor, Claude, Codex) conservan su cuenta.

Objetivo#

Dar al gateway local de Orchemax tus API keys de proveedores (con failover si una clave o un proveedor se queda sin cuota) y apuntar solo los asientos que usan keys. Los asientos con login + plan de tokens del vendor (Cursor, Claude Code con suscripción, Codex, …) se quedan en ese login — el gateway no lo reemplaza.

Gateway solo donde aplica#

Tipo de asiento Ejemplos Tráfico de modelos
Cuenta / plan Cursor, Claude Code (Pro/Max), Codex Login del vendor. Default agents.auth: account. No gateway connect.
API key / BYO OpenCode, OpenClaude, Command Code, Copilot con key, Cursor BYOK Keys en keys.env de machine-home → anillo del gateway.

Orchemax sigue debajo de todos los asientos para MCP, bus, locks y usage. Solo el enrutado de modelos por :8788 es opcional y por asiento.

Cómo funciona la rotación (asientos con API key)#

  1. Pones una o más keys por proveedor en keys.env del machine-home (OPENROUTER_API_KEY=…; varias separadas por coma = anillo).
  2. Registras providers en ai.yaml (orch gateway setup --live …).
  3. Arrancas orch gateway (por defecto http://127.0.0.1:8788).
  4. Esos agentes hablan solo con Orchemax. Orchemax elige el siguiente provider / la siguiente key ante 429 o cuota — el agente no gestiona la rotación.

Los asientos con plan omiten el paso 4 a propósito.

asiento con API key (OpenCode / OpenClaude / …)
        │  Base URL = http://127.0.0.1:8788/v1
        │  API key  = orch_gk_…   (virtual; no es tu secreto)
        ▼
orch gateway  (:8788)
        │  anillo por proveedor: key1 → key2 → key3 ante 429
        ▼
OpenRouter / Groq / Cerebras / …

Cursor / Claude (plan) / Codex
        │  su propio login
        ▼
API de modelos del vendor   (orch debajo para MCP/bus — no enruta el modelo)

Las keys upstream viven solo en machine-home (keys.env). El agente con API key nunca las ve. Varias keys en la misma variable = rotación automática.

Pasos#

1. Keys donde Orchemax las lee#

Preferible el archivo (no las variables de entorno de Windows):

%LOCALAPPDATA%\Orchemax\keys.env (o ORCH_HOME)

OPENROUTER_API_KEY=sk-or-…
CEREBRAS_API_KEY=…
GROQ_API_KEY=…

O una a una (se prueba antes de guardar):

orch gateway keys add openrouter

2. Registrar providers (una vez)#

orch gateway setup --live \
  --name openrouter \
  --url https://openrouter.ai/api/v1 \
  --model openrouter/auto \
  --key-env OPENROUTER_API_KEY \
  --tier cheap \
  --priority 10

Repite para otros. Menor priority = se prueba primero. Verifica con orch gateway show — cada línea debe decir key=set y ai.mode=live.

El orch.yaml del workshop no debe dejar ai.mode: stub o tapa el catálogo de usuario.

3. Arrancar el gateway#

orch gateway

Déjalo corriendo mientras usas agentes con API key.

4. Apuntar agentes con API key a Orchemax (por protocolo)#

Cientos de agentes comparten dos cables. Orchemax no escribe un settings por CLI:

orch gateway connect              # paste OpenAI-compat (default)
orch gateway connect openai       # igual
orch gateway connect anthropic    # paste Anthropic Messages (solo asientos con API key)
orch gateway connect opencode --allow-user-scope   # opcional: escribe el JSON de OpenCode

Aliases como openclaude, commandcode, copilot, cursor imprimen el bloque openai. Alias claude → anthropic.

Command Code es especial: orch gateway connect commandcode --allow-user-scope escribe ~/.commandcode/providers.json con "apiKey": "$ORCH_GATEWAY_KEY" (no un orch_gk_… pegado). Ese CLI rechaza keys en claro ("Provider 'orch' has no API key"). El heal lo dispara el hint de catálogo BYOKProvidersRel (cualquier CLI con el mismo schema $ENV_VAR puede setearlo) — no es una whitelist de nombres. Los asientos con gateway routing y ese hint sincronizan el archivo al lanzar.

No corras connect para asientos Cursor / Claude / Codex con plan. Cualquier agente BYO OpenAI-compat: pega Base URL http://127.0.0.1:8788/v1 y la clave virtual orch_gk_…. Modelos: GET /v1/models (ids reales upstream).

Matriz por protocolo

Protocolo Connect Quién
OpenAI-compat openai (default) OpenCode (o opencode --allow-user-scope), OpenClaude, Command Code, Copilot BYOK, Cursor BYOK, …
Anthropic Messages anthropic / claude Claude Code con API key + agents.auth.claude: gateway
Cuenta / plan — Cursor suscripción, Claude plan, Codex — sin connect

En un connect OpenAI-compat obtienes:

  • Base URL → http://127.0.0.1:8788/v1
  • API key → clave virtual de Orchemax (orch_gk_…), no tu secreto upstream
  • Modelos → GET /v1/models en el gateway (ids reales del proveedor)

5. Verificar que la rotación vive#

orch gateway status
orch gateway usage

status muestra live/cooldown y posición del anillo (2/3). usage muestra llamadas y ahorro tras tráfico real.

Ejemplo: OpenCode con rotación#

# 1) Varias keys = anillo (coma).
OPENROUTER_API_KEY=sk-or-aaa,sk-or-bbb
GROQ_API_KEY=gsk-…

# 2) Catálogo (una vez por máquina)
orch gateway setup --live --name openrouter --url https://openrouter.ai/api/v1 \
  --model openrouter/auto --key-env OPENROUTER_API_KEY --tier cheap --priority 10
orch gateway setup --live --name groq --url https://api.groq.com/openai/v1 \
  --model llama-3.3-70b-versatile --key-env GROQ_API_KEY --tier cheap --priority 20

# 3) Proxy + paste OpenAI-compat en cualquier agente BYO
orch gateway
orch gateway connect                 # imprime Base URL + clave virtual
# opcional escritura de OpenCode:
# orch gateway connect opencode --allow-user-scope

# 4) Comprueba el anillo
orch gateway status

Asientos con plan/login del vendor#

Si agents.auth.<preset> es account (default de Cursor, Codex, y Claude sin API key de Anthropic), connect solo imprime ORCH_GATEWAY_* y conserva el login. Eso es correcto — déjalo así. Notas de campo y anti-patrones: ajustes comunes — asientos con login/plan.

Para forzar gateway en un asiento que sí puede usar API keys:

agents:
  auth:
    claude: gateway   # solo con API key de Anthropic configurada

Deshacer#

orch gateway keys remove <provider> <hint>

Quita el override de base URL / key del agente, o pon agents.auth.<preset>: account.

Relacionado#