Claude Code ↔ Alibaba Cloud Token Plan proxy

Español | English

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.

• 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.

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:

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.

Related MCP server: ccg-mcp

Modelos

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

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.

Fuentes de protocolo: contrato de gateways de Claude Code, Messages compatible de Alibaba y allowlist del Token Plan.

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:

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:

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:

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. 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, API Wan 2.7, modelos HappyHorse y MCP en Claude Code.

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:

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:

$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. 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):

{
  "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.

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:

/model

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

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:

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

Messages con streaming:

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

Ejemplo de override deliberado:

$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

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

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

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.