# Claude Code ↔ Alibaba Cloud Token Plan proxy

[Español](README.md) | [English](README.en.md)

Proxy local y liviano que completa la interfaz Anthropic de Alibaba Cloud para
Claude Code:

Versión actual: **0.1.0**. Consulta los cambios en
[`CHANGELOG.md`](CHANGELOG.md).

- sirve `GET /v1/models`, que el endpoint Anthropic-compatible de Alibaba no
  implementa;
- traduce alias descubribles por Claude Code a los IDs reales de Alibaba;
- reenvía `POST /v1/messages` y su streaming SSE sin almacenarlo ni
  reconstruirlo;
- conserva headers `anthropic-*`, campos beta, tool calls, thinking y errores
  del upstream;
- no tiene dependencias de runtime: usa únicamente Node.js.

```text
Claude Code ── Anthropic Messages ──> proxy local ──> Alibaba Token Plan
              /v1/models (local)      alias → ID      /v1/messages
```

## Endpoint Anthropic

La base URL Anthropic que debes configurar en Claude Code es:

```text
http://127.0.0.1:8787
```

El proxy expone:

- Messages: `POST http://127.0.0.1:8787/v1/messages`
- Model discovery: `GET http://127.0.0.1:8787/v1/models`
- Token counting opcional:
  `POST http://127.0.0.1:8787/v1/messages/count_tokens`

No agregues `/v1` a `ANTHROPIC_BASE_URL`: Claude Code lo añade al construir
cada request.

## Modelos

Claude Code solo acepta por descubrimiento IDs que comiencen con `claude` o
`anthropic`. Por eso el proxy publica alias y los mapea así:

| Selector de Claude Code | ID enviado a Alibaba |
| --- | --- |
| `claude-qwen3.8-max-preview` | `qwen3.8-max-preview` |
| `claude-glm-5.2` | `glm-5.2` |
| `claude-qwen3.7-max` | `qwen3.7-max` |
| `claude-deepseek-v4-pro` | `deepseek-v4-pro` |
| `claude-qwen3.7-plus` | `qwen3.7-plus` |
| `claude-qwen3.6-flash` | `qwen3.6-flash` |

Los seis IDs reales también se aceptan en llamadas directas, aunque Claude Code
no los agrega al selector porque no pasan su filtro de nombres.

> [!IMPORTANT]
> La lista oficial del Token Plan consultada el 23 de julio de 2026 no incluye
> `qwen3.8-max-preview`; sí incluye los otros cinco IDs de la tabla. El proxy lo
> expone porque es un requisito de este proyecto y no lo sustituye
> silenciosamente. Si tu cuenta todavía no lo tiene habilitado, Alibaba
> devolverá su error original.

Fuentes de protocolo:
[contrato de gateways de Claude Code](https://code.claude.com/docs/en/llm-gateway-protocol),
[Messages compatible de Alibaba](https://www.alibabacloud.com/help/en/model-studio/anthropic-api-messages)
y [allowlist del Token Plan](https://www.alibabacloud.com/help/en/model-studio/token-plan-overview).

## Requisitos

- Node.js 22.13 o posterior. Las dependencias multimedia se instalan
  automáticamente en el primer inicio de la interfaz.
- Claude Code 2.1.129 o posterior para model discovery.
- Una API key dedicada del Alibaba Cloud Token Plan.

## Interfaz gráfica para Windows

Haz doble clic en el lanzador silencioso:

```text
ClaudeAlibabaProxy.vbs
```

No abre ni mantiene una consola de CMD o PowerShell. El archivo
`ClaudeAlibabaProxy.bat` queda disponible como alternativa compatible y
también delega al lanzador silencioso antes de cerrarse.

El lanzador abre una interfaz nativa de Windows desde la que puedes:

- ingresar la API key y el endpoint de Alibaba;
- elegir host, puerto y modelo predeterminado;
- generar el token local del proxy;
- iniciar y detener el servidor sin una consola abierta;
- abrir una guía paso a paso en pestañas separadas para español e inglés;
- cambiar toda la interfaz entre español e inglés desde el selector discreto
  **Idioma / Language**;
- instalar `%USERPROFILE%\.claude\settings.json`, conservando sus opciones y
  creando un backup del archivo anterior;
- instalar `.claude\settings.local.json` para activar Alibaba solo en este
  repositorio y conservar tu subscripción de Claude Code en el resto;
- guardar opcionalmente la configuración en `.env`;
- generar y editar imágenes con Wan 2.7;
- estimar y enviar tareas HappyHorse;
- consultar, esperar y descargar tareas de video;
- registrar el servidor MCP multimedia en Claude Code;
- abrir, copiar y restaurar respaldos de `settings.json`;
- minimizarse al área de notificación de Windows sin detener el proxy;
- mantener el proxy activo al pulsar la **X** o `Alt+F4`: un doble clic en el
  icono restaura la ventana, y **Salir** queda bloqueado hasta pulsar
  **Detener**.

El lanzador busca Node 22.13+ en el `PATH`, en las ubicaciones habituales de
Windows y en el runtime local incluido con Codex. El build JavaScript
precompilado está en `dist/`, por lo que no necesita ejecutar `pnpm` al abrir
la interfaz. Si faltan las dependencias de `media-mcp`, el primer inicio las
instala con `pnpm`, `corepack` o `npm`, según lo disponible.

La API key solo se persiste si pulsas **Guardar .env** y confirmas la
advertencia. El archivo queda excluido de Git, pero contiene las credenciales
en texto plano.

Al pulsar **Instalar settings.json**, la interfaz muestra y confirma la ruta,
crea la carpeta `.claude` si hace falta y escribe directamente un único objeto
JSON válido. Si el archivo ya existe, conserva permisos, hooks y demás opciones
y crea un backup fechado antes de reemplazarlo. El JSON final también queda en
el portapapeles.

Si el JSON existente es inválido, el launcher lo rechaza y no lo reemplaza.
Las acciones **Copiar JSON** e **Instalar settings.json** son independientes:
la primera usa el portapapeles y la segunda escribe, relee y verifica el
archivo real.

## Credenciales en paralelo

Claude Code no mezcla la subscripción de Claude.ai y un gateway custom en la
misma sesión. Cuando `ANTHROPIC_BASE_URL` apunta al proxy local, esa sesión usa
Alibaba Token Plan.

El modo recomendado es instalar Alibaba con alcance local del repositorio:
`.claude\settings.local.json`. Así tu login/subscripción de Claude Code queda
en `%USERPROFILE%\.claude` y sigue funcionando en los demás repositorios. Usa el
alcance **Global** solo si quieres que Alibaba reemplace el backend en todas tus
sesiones.

## Imagen y video mediante MCP

Wan y HappyHorse no aparecen en `/model`. Claude Code los descubre como
herramientas del servidor local `alibaba-media`:

```text
Claude Code
  +-- /v1/messages -> proxy de texto
  +-- MCP alibaba-media
        +-- wan_generate_image
        +-- wan_edit_image
        +-- wan_estimate_cost
        +-- diez herramientas happyhorse_*
```

Wan utiliza la misma key `sk-sp-` de Token Plan y el endpoint multimedia
dedicado:

```text
https://token-plan.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
```

HappyHorse utiliza una key Model Studio de Singapur y el endpoint público
compartido `https://dashscope-intl.aliyuncs.com`; no requiere Workspace ID.
Configura permisos Custom solo para `happyhorse-1.1-t2v`,
`happyhorse-1.1-i2v`, `happyhorse-1.1-r2v` y
`happyhorse-1.0-video-edit`. OSS es opcional y la GUI solo lo muestra para
editar un video local. HappyHorse puede facturarse fuera del Token Plan.

El código multimedia vive en [`media-mcp`](media-mcp). El launcher lo registra
con alcance `user`, por lo que queda disponible en todos tus proyectos de
Claude Code después de reiniciarlo.

Referencias:
[integración multimedia de Token Plan](https://www.alibabacloud.com/help/en/model-studio/token-plan-multimodal-gen),
[API Wan 2.7](https://www.alibabacloud.com/help/en/model-studio/wan-image-generation-and-editing-api-reference),
[modelos HappyHorse](https://www.alibabacloud.com/help/en/model-studio/video-generate-edit-model)
y [MCP en Claude Code](https://code.claude.com/docs/en/mcp).

El artefacto recomendado en Windows es `ClaudeAlibabaProxy.vbs`, que inicia la
GUI sin una consola visible. `ClaudeAlibabaProxy.bat` se conserva como entrada
compatible. No se incluye un `.exe` sin firma porque sería únicamente otro
envoltorio del mismo PowerShell, añadiría advertencias de SmartScreen y no
eliminaría el requisito de Node.js. Un `.exe` firmado puede añadirse más
adelante si existe un certificado de firma de código y una necesidad real de
distribución administrada.

## Inicio rápido en Windows

Si prefieres usar la terminal:

Instala dependencias y compila:

```powershell
corepack enable
pnpm install
pnpm build
```

Inicia el proxy. La key queda únicamente en el proceso local y nunca se envía a
Claude Code:

```powershell
$env:ALIBABA_API_KEY = "sk-sp-tu-key"
$env:PROXY_AUTH_TOKEN = "elige-un-secreto-local"
pnpm start
```

El servicio escucha por defecto en `http://127.0.0.1:8787`.

También puedes copiar y editar [`examples/start.ps1`](examples/start.ps1). El
archivo `.env` se usa automáticamente con Docker Compose; Node no lo carga por
sí solo.

## Configurar Claude Code

Para usar Alibaba solo en este repositorio, guarda este bloque en
`.claude\settings.local.json` dentro del repo. Para usar Alibaba globalmente,
combínalo con `%USERPROFILE%\.claude\settings.json` existente (debe quedar un
solo objeto JSON):

```json
{
  "model": "claude-qwen3.8-max-preview",
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8787",
    "ANTHROPIC_AUTH_TOKEN": "elige-un-secreto-local",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING": "1"
  }
}
```

El valor de `ANTHROPIC_AUTH_TOKEN` debe coincidir con
`PROXY_AUTH_TOKEN`. Hay una copia lista para editar en
[`examples/claude-settings.json`](examples/claude-settings.json).

Para volver a tu subscripción, abre Claude Code fuera de un repositorio que tenga
`.claude\settings.local.json` de Alibaba o elimina esas variables del alcance
activo.

Reinicia Claude Code y ejecuta:

```text
/model
```

Los seis modelos aparecerán con la etiqueta **From gateway**. Para comprobar el
arranque con detalle:

```powershell
claude --debug
```

Busca líneas `[gatewayDiscovery]`. No configures
`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1`: esa variable también desactiva
model discovery.

## Probar sin Claude Code

Descubrimiento:

```powershell
curl.exe http://127.0.0.1:8787/v1/models `
  -H "Authorization: Bearer elige-un-secreto-local"
```

Messages con streaming:

```powershell
curl.exe --no-buffer http://127.0.0.1:8787/v1/messages `
  -H "Authorization: Bearer elige-un-secreto-local" `
  -H "Content-Type: application/json" `
  -H "anthropic-version: 2023-06-01" `
  -d '{\"model\":\"claude-qwen3.7-plus\",\"max_tokens\":256,\"stream\":true,\"messages\":[{\"role\":\"user\",\"content\":\"Hola\"}]}'
```

## Variables de entorno

| Variable | Obligatoria | Default | Uso |
| --- | --- | --- | --- |
| `ALIBABA_API_KEY` | sí | — | Key dedicada del Token Plan |
| `ALIBABA_BASE_URL` | no | endpoint Token Plan de Singapur | Base Anthropic-compatible, sin `/v1` final |
| `HOST` | no | `127.0.0.1` | Interfaz de escucha |
| `PORT` | no | `8787` | Puerto local |
| `PROXY_AUTH_TOKEN` | no | sin auth local | Credencial que presenta Claude Code |
| `MAX_BODY_BYTES` | no | `33554432` | Límite del JSON de entrada |
| `MODEL_MAP` | no | tabla anterior | Overrides JSON alias → ID upstream |
| `DASHSCOPE_API_KEY` | solo HappyHorse | — | Key Model Studio de Singapur |
| `ALIBABA_WORKSPACE_ID` | no | vacío | Si se define manualmente, usa el endpoint dedicado en vez del público |
| `OSS_ENDPOINT` y `OSS_BUCKET` | solo edición de video local | — | Almacenamiento temporal de la entrada |
| `OSS_ACCESS_KEY_ID` y `OSS_ACCESS_KEY_SECRET` | solo edición de video local | — | Credenciales OSS limitadas |

Ejemplo de override deliberado:

```powershell
$env:MODEL_MAP = '{"claude-qwen3.8-max-preview":"otro-id-habilitado"}'
```

Solo se aceptan como keys los seis alias documentados, para detectar typos al
arrancar.

## Endpoints

| Método | Ruta | Comportamiento |
| --- | --- | --- |
| `HEAD` | `/` | Probe de conectividad de Claude Code |
| `GET` | `/health` | Health check público |
| `GET` | `/v1/models` | Catálogo local para Claude Code |
| `GET` | `/v1/models/:id` | Metadata de un alias |
| `POST` | `/v1/messages` | Proxy con traducción de modelo |
| `POST` | `/v1/messages/count_tokens` | Pass-through opcional; Alibaba puede responder 404 |

El proxy reenvía los errores HTTP y el body de Alibaba sin envolverlos, para no
romper los retries automáticos de Claude Code. En streaming, cada chunk se
escribe al cliente en cuanto llega y respeta backpressure.

## Docker

```powershell
Copy-Item .env.example .env
# Edita .env y reemplaza las dos credenciales.
docker compose up --build
```

Compose publica el puerto solo en `127.0.0.1`. Si lo expones en otra interfaz,
mantén `PROXY_AUTH_TOKEN` configurado y agrega TLS mediante un reverse proxy.

## Desarrollo

```powershell
pnpm typecheck
pnpm test
pnpm test:launcher
pnpm build
```

Los tests cubren discovery y auth, traducción de modelos y headers, streaming,
rechazo de IDs desconocidos, contratos MCP, persistencia HappyHorse,
idempotencia, validación de archivos, estimación y generación Wan simulada.

La separación es intencional:

- `src/models.ts`: catálogo y resolución de alias;
- `src/proxy.ts`: Anthropic Messages hacia Alibaba;
- `src/http.ts`: transporte, errores y streaming;
- `src/app.ts`: rutas y extensión mediante `ProxyRoute`.

Wan 2.7 y HappyHorse no se mezclan con `/v1/messages`: el subpaquete
`media-mcp` conserva sus contratos y procesos separados. La GUI es la capa que
los presenta como una sola aplicación.

## Límites y seguridad

- El proxy de texto no guarda prompts. El MCP guarda metadatos de tareas, no el
  prompt completo por defecto.
- La key de Alibaba siempre reemplaza cualquier credential recibida del cliente.
- `PROXY_AUTH_TOKEN` es opcional para localhost, pero recomendado.
- El Token Plan autoriza uso interactivo con herramientas de programación y
  agentes; no despliegues este proyecto como backend general ni compartas la key
  asignada a tu asiento.

MIT.