Llaves de gateway y connect

Agrega llaves de proveedores upstream al anillo de rotacion del gateway local, y conecta CLIs de agentes a el.

Objetivo#

Darle al gateway local de orch las llaves API de proveedores upstream (con failover automatico ante rate limits), y luego conectar CLIs de agentes — OpenCode, Command Code, herramientas OpenAI-compat, o Claude Code — para que su trafico de modelos pase por el.

Pasos#

Agrega una llave al anillo de rotacion de un proveedor:
```
orch gateway keys add openai sk-...
```
Si omites la llave, te la pide por prompt. La llave se prueba contra el proveedor antes de guardarse — si la prueba falla, imprime por que y no guarda nada. Las llaves viven en el vault de machine-home (keys.env), una variable de entorno por proveedor; varias llaves separadas por coma forman un anillo que el gateway ya sabe rotar ante 429s.
Lista las llaves configuradas (solo hints — nunca se imprime una llave completa):
```
orch gateway keys list [provider]
```
Imprime <provider> tier=<tier> keys=<n> <hints...>.

Quita una llave por su hint:

orch gateway keys remove openai sk-…abcd

Inicia el gateway:
```
orch gateway
```

Conecta un agente al gateway:

orch gateway connect opencode      # escribe ~/.config/opencode/opencode.json automaticamente
orch gateway connect commandcode   # imprime el env para Command Code
orch gateway connect openai        # imprime env + un snippet de config de OpenCode
orch gateway connect claude        # imprime variables de entorno de Anthropic

OpenCode es el unico destino que orch edita por ti; los demas imprimen ORCH_GATEWAY_BASE / ORCH_GATEWAY_KEY (y, para openai/claude, las variables OPENAI_* / ANTHROPIC_* correspondientes) para que las exportes o las pegues en la configuracion de la herramienta.

Si el agents.auth de un preset es account (el default para codex, cursor, y claude sin llave passthrough — ver configure-agents.md), orch gateway connect solo imprime ORCH_GATEWAY_* y una advertencia:

# warning: claude keeps its own plan login; orch injects only ORCH_GATEWAY_*;
# set agents.auth.claude: gateway to route model traffic through orch

Las variables de proveedor se omiten a proposito — imprimir OPENAI_API_KEY o ANTHROPIC_AUTH_TOKEN encima de un login de plan reemplazaria ese login silenciosamente y le quitaria sus conectores. Define agents.auth.<preset>: gateway explicitamente primero si eso es lo que quieres.

Verificar#

orch gateway status

Lee /v1/providers/stats del gateway corriendo: el estado vivo/enfriamiento por proveedor, la posicion en el anillo de llaves (2/3), y los conteos de rotacion y enfriamiento desde que arranco el gateway. Los contadores se reinician al reiniciar el gateway — para un registro historico usa orch gateway usage / orch usage.

Deshacer#

orch gateway keys remove <provider> <hint>

Para dejar de enrutar un agente por el gateway, quita su agents.auth.<preset> (o ponlo en account) y vuelve a exportar el login/env propio del CLI.

Relacionado#

configure-agents.md — agents.auth y agents.transport por preset.
troubleshooting.md — orch usage y la contabilidad de tokens de seats con plan.