---
title: |-
  Playbook *UC1*
  Proxy multi-provider
description: "Verificación: sesión Claude Code con provider alternativo (MiniMax) a través del proxy multi-provider. El use case más básico del ecosistema."
kicker: Playbook · UC1 · Proxy Session
subtitle: |-
  `cl minimax --proxy` — sesión Claude Code con MiniMax a través del
  gateway-proxy. Verifica que el proxy enruta correctamente, que las virtual keys
  funcionan y que la sesión produce output esperado.
strip:
  - { k: PLAYBOOK, v: UC1-PROXY }
  - { k: REV, v: "1.0" }
  - { k: FECHA, v: 21 JUN 2026 }
  - { k: DEPENDE, v: P0 }
meta:
  - { k: Esfuerzo, v: 5 min }
  - { k: Depende de, v: P0 (prerequisites) }
  - { k: Bloquea, v: UC3 (channels) }
  - { k: Veredicto, v: ⏳ pendiente }
stamps:
  - { text: Proxy prod vivo, tone: ok }
toc_legend:
  - { text: verificado, tone: ok }
  - { text: fallo esperable, tone: warn }
  - { text: roto, tone: bad }
footer:
  left: |-
    **UC1-PROXY · REV 1.0**
    Playbooks de verificación E2E para mks-agentics
  right: |-
    **PROXY** público · **MINIMAX** provider · **VIRTUAL KEY**
---

## Objetivo {#objetivo}

El use case más básico: abrir una sesión Claude Code en Mac usando un provider alternativo (MiniMax) a través del gateway-proxy. Esto verifica que el proxy enruta correctamente y que todo el stack de autenticación (virtual key → proxy → upstream provider) funciona. {.lead}

```dossier:diagram
engine: d2
source: |
  direction: right

  cli: "cl minimax --proxy" {
    style: {
      fill: "#1a1a2e"
      stroke: "#e94560"
    }
  }

  proxy: "gateway-proxy\n:3200 local o\nproxy.gateway.mks2508.systems" {
    style: {
      fill: "#0f3460"
      stroke: "#533483"
    }
  }

  upstream: "MiniMax API\napi.minimax.io/anthropic" {
    style: {
      fill: "#16213e"
      stroke: "#0f3460"
    }
  }

  cli -> proxy: "ANTHROPIC_BASE_URL\n+ virtual key sk-mks-*" {
    style.stroke-dash: 3
  }
  proxy -> upstream: "Messages API\n(anthropic-native)" {
    style.stroke-dash: 3
  }
```

## F1 — Sesión *básica* con proxy local {#f1-local}

```dossier:phases
items:
  - dur: "2 min"
    title: Arrancar sesión con proxy
    checks:
      - text: "`cl minimax --proxy` → Claude Code arranca sin errores"
        sub: El shell `cl()` configura proxy local y lanza Claude Code
      - text: "Escribir 'di hola' → respuesta del modelo"
        sub: Verificar que el proxy enruta al provider y el modelo responde
      - text: "La respuesta NO contiene errores de auth (401/403)"
        sub: La virtual key o el token son válidos
```

### Comandos de verificación

```dossier:term
title: Proxy local — verificación
content: |
  # Antes de arrancar, verificar que el proxy local está corriendo:
  $ curl -s http://127.0.0.1:3200/health
  → {"status":"ok"}

  # Verificar providers disponibles:
  $ curl -s http://127.0.0.1:3200/v1/providers | jq 'keys'
  → ["glm","minimax","deepseek"]

  # Lanzar Claude Code con MiniMax via proxy:
  $ cl minimax --proxy

  # Dentro de Claude Code, probar:
  > di hola en español
  → (respuesta del modelo MiniMax en español)

  # Verificar que el proxy usó el provider correcto:
  # En otra terminal:
  $ tail -f /tmp/gateway-proxy.log  # si el proxy está logueando
```

## F2 — Proxy *público* remoto {#f2-remoto}

```dossier:phases
items:
  - dur: "3 min"
    title: Verificar proxy público
    checks:
      - text: "`curl -s https://proxy.gateway.mks2508.systems/health` → 200 OK"
        sub: Proxy público accesible
      - text: "`curl -s https://proxy.gateway.mks2508.systems/v1/providers` → JSON con providers"
        sub: Data-plane público lista providers
      - text: "Crear virtual key con `gateway-proxyctl key create` → `sk-mks-...`"
        sub: Se necesita OIDC admin session para crear keys
      - text: "`curl -s https://proxy.gateway.mks2508.systems/v1/models -H 'x-api-key: sk-mks-...'` → 200"
        sub: Virtual key válida aceptada por el data-plane
```

```dossier:table
caption: Modos de conexión al proxy
columns:
  - { h: Modo }
  - { h: Comando }
  - { h: Proxy URL }
  - { h: Auth }
  - { h: Cuándo usarlo }
rows:
  - cells:
      - Local sin auth
      - "`cl minimax proxy`"
      - http://127.0.0.1:3200
      - "proxy-dummy (sin auth)"
      - Desarrollo local rápido
  - cells:
      - Local con virtual key
      - "`cl minimax proxy` + virtual key en ~/.claudio.json"
      - http://127.0.0.1:3200
      - "sk-mks-*"
      - Desarrollo con tracking de usage
  - cells:
      - Remoto VPN
      - "`claudio minimax --env --proxy`"
      - lab1-helsinki.gateway-proxy.vpn...
      - "sk-mks-*"
      - Producción sobre VPN
  - cells:
      - Remoto público
      - (no implementado en claudio aún)
      - proxy.gateway.mks2508.systems
      - "sk-mks-*"
      - Tier-2 público
```

```dossier:note
tone: warn
tag: Limitación actual de claudio
body: |
  `claudio --proxy` solo soporta proxy **remoto sobre VPN** (configurado vía `claudio proxy set`).
  El `cl() { }` en zshrc hardcodea `127.0.0.1:3200` para `--proxy`, que es el proxy local.

  Para usar el proxy **público** (`proxy.gateway.mks2508.systems`) desde Claude Code, habría que:
  1. Setear manualmente `ANTHROPIC_BASE_URL=https://proxy.gateway.mks2508.systems`
  2. Setear `ANTHROPIC_AUTH_TOKEN=sk-mks-...`
  3. O extender `claudio` con un modo `--public-proxy`

  Esto es un gap conocido — no bloquea los playbooks porque UC1 se verifica con proxy local.
```

## F3 — Cambio de *provider* {#f3-hotswitch}

```dossier:phases
items:
  - dur: "2 min"
    title: Verificar routing por provider
    checks:
      - text: "`cl deepseek --proxy` → arranca con DeepSeek"
        sub: Cambiar provider a DeepSeek vía proxy
      - text: "`cl glm --proxy` → arranca con GLM"
        sub: Cambiar provider a GLM vía proxy
      - text: "Cada provider produce respuestas (no errores de API key)"
        sub: Las API keys están configuradas en el proxy o en ~/.claudio.json
```

```dossier:questions
items:
  - no: Q1
    title: "¿Responde el modelo?"
    chip: { text: básico, tone: ok }
    body: Después de `cl minimax --proxy`, escribir un prompt simple
    branches:
      - tone: "yes"
        label: "Sí → respuesta normal"
        text: UC1 verde. El proxy + provider funcionan.
      - tone: "no"
        label: "No → error o timeout"
        text: "Revisar: (1) ¿está el proxy corriendo? `curl :3200/health`, (2) ¿está MINIMAX_API_KEY seteada en el proxy?, (3) ¿hay conectividad a api.minimax.io?"
  - no: Q2
    title: "¿La respuesta es del modelo esperado?"
    chip: { text: calidad, tone: warn }
    body: Verificar que el modelo responde en el idioma y estilo esperado
    branches:
      - tone: "yes"
        label: "Sí → MiniMax"
        text: El proxy enrutó correctamente a MiniMax.
      - tone: "no"
        label: "No → otro provider"
        text: "Revisar routing en ~/.gateway-proxy.json. Puede que el defaultProvider sea otro."
```

```dossier:sources
groups:
  - title: Código relevante
    items:
      - label: gateway-proxy app.ts
        url: apps/gateway-proxy/src/app.ts
        chip: { text: source }
      - label: claudio index.ts
        url: ~/dotfiles/claude-model/src/index.ts
        chip: { text: source }
      - label: zshrc cl() function
        url: ~/dotfiles/macos/zshrc
        chip: { text: config }
      - label: key-store.service.ts
        url: apps/gateway-proxy/src/service/keys/key-store.service.ts
        chip: { text: source }
```