Roo Code es un agente de programación muy usado en VS Code, con soporte para múltiples modos, asignación de modelos por modo y proveedores personalizados compatibles con OpenAI. Para los equipos que trabajan desde China continental, conectarlo a un gateway unificado permite fijar la ruta de acceso, centralizar la facturación y controlar la cuota por proyecto.

Antes hay que aclarar un cambio: según el anuncio del repositorio de Roo Code, Roo Code, Inc. suspendió la extensión Roo Code el 15 de mayo de 2026 y el repositorio principal se archivó ese mismo día; la última versión fue la v3.54.0. La bifurcación comunitaria Zoo Code continúa el mantenimiento y conserva buena parte de los métodos de configuración originales. Este artículo se centra en Zoo Code y señala las diferencias de la versión anterior de Roo Code.

Nota: Roo Code es una marca de Roo Code, Inc.; Zoo Code es un proyecto bifurcado de la comunidad; VS Code es una marca de Microsoft Corporation; OpenAI es una marca de OpenAI, Inc. Este artículo solo ofrece una explicación técnica y no implica afiliación ni relación de colaboración con esas entidades. El estado del proyecto, la interfaz y los menús se rigen por los anuncios del repositorio y la documentación de la versión actual.

1. Confirma si usas Roo Code o Zoo Code

Los paneles y la configuración de proveedores son muy parecidos, pero el estado de mantenimiento es distinto:

  • Roo Code: el ID de la extensión es RooVeterinaryInc.roo-cline; el repositorio principal se archivó el 15 de mayo de 2026 y la extensión dejó de actualizarse. La versión instalada puede seguir funcionando, pero ya no recibirá correcciones ni adaptaciones a modelos nuevos.
  • Zoo Code: nace de una bifurcación de la comunidad de Roo Code, usa licencia Apache-2.0, se publica en VS Code Marketplace como ZooCodeOrganization.zoo-code y su documentación está en docs.zoocode.dev. Mantiene los modos Code, Architect, Ask, Debug y otros.
  • El directorio de configuración original de Roo Code, .roomodes y .rooignore se conservan, así que la migración suele reaprovecharlos; los pasos exactos se rigen por la documentación de migración de Zoo Code.
  • Cuando un equipo unifica la configuración, primero confirma que todos tengan instalada la misma extensión. Mezclar la versión antigua de Roo Code con Zoo Code puede producir menús y opciones inconsistentes.

2. Prepara la clave, la Base URL y el modelo

Antes de empezar necesitas tres elementos: una clave de API, una dirección compatible con OpenAI y un ID de modelo exacto.

  1. Abre la página de registro de ZSQH AI Gateway, regístrate e inicia sesión en la consola.
  2. Entra en «Claves de API», crea una clave nueva y ponle un nombre que describa su uso, por ejemplo zoo-code-equipo.
  3. Define un límite de cuota y una fecha de expiración. También conviene hacerlo en cuentas personales para evitar consumos anómalos.
  4. Copia la clave y guárdala en un gestor de contraseñas. Por lo general, la consola solo la muestra completa una vez.
  5. Abre precios de modelos y anota el ID del modelo que vas a usar. Los precios y los modelos cambian, así que toma como referencia lo que muestre la página en ese momento.

Los tres valores de configuración se escriben así:

API Provider: OpenAI Compatible
Base URL:     https://ai.zhongshangqihang.com/v1
API Key:      sk-... (creada en la consola, guardada solo en el gestor de contraseñas)
Model:        el ID de modelo que muestre la página de precios del sitio

La Base URL usa la dirección compatible con OpenAI y termina en /v1. No pongas la dirección raíz de Anthropic ni añadas /chat/completions por tu cuenta; de lo contrario, es fácil que la ruta se duplique y aparezca un 404.

3. Instala la extensión en VS Code

Zoo Code requiere VS Code 1.84.0 o superior. Pasos de instalación:

  1. Abre VS Code y pulsa Cmd/Ctrl + Shift + X para ir a la vista de extensiones.
  2. Busca Zoo Code, elige la entrada cuyo editor sea ZooCodeOrg e instálala.
  3. Si todavía usas la versión antigua de Roo Code, busca Roo Code, con editor RooVeterinaryInc; ten en cuenta que ya no recibe mantenimiento.
  4. Cuando termine la instalación, recarga VS Code según la indicación. Aparecerá un icono en la barra de actividad; haz clic para abrir el panel.
  5. En editores sin Marketplace, como VSCodium o Windsurf, busca la extensión con el mismo nombre en Open VSX o descarga el VSIX desde Releases y instálalo manualmente.
  6. Si el icono no aparece después de instalar, reinicia VS Code, confirma que la extensión está habilitada y revisa el canal de salida correspondiente en View → Output.

4. Configura el proveedor OpenAI Compatible

Abre el panel de configuración de la extensión y elige OpenAI Compatible en la lista API Provider. Esta opción está pensada para servicios compatibles que no son la dirección oficial de OpenAI y no es el mismo punto de entrada que el proveedor OpenAI integrado.

Campos que debes rellenar y revisar:

  • Base URL: escribe https://ai.zhongshangqihang.com/v1, sin /chat/completions.
  • API Key: pega la clave creada en la consola; comprueba que no tenga espacios ni saltos de línea.
  • Model: escribe el ID del modelo, no el nombre visible ni una nota.
  • Model Configuration: si hace falta, completa Context Window, Max Output Tokens, Image Support, Computer Use y los precios de entrada y salida. Los campos de precio solo afectan a la estimación de costo en la interfaz y no cambian la facturación real; si no estás seguro, déjalos vacíos.
  • Llamadas a herramientas: el proveedor OpenAI Compatible de Zoo Code y Roo Code solo admite llamadas nativas de OpenAI, sin respaldo XML. El modelo elegido debe soportar function calling compatible con OpenAI; de lo contrario, el chat normal puede funcionar, pero el agente fallará al leer o escribir archivos.

Si el gateway solo implementa parte del protocolo de herramientas, valida primero en una conversación normal y después prueba con un archivo pequeño. No empieces directamente con una refactorización de varios archivos, porque será difícil saber dónde está el problema.

5. Cómo combinar modelos y modos

Roo Code y Zoo Code admiten varios modos y permiten asignar un modelo distinto a cada uno. Así se reparte el equilibrio entre costo y capacidad:

Modo o escenario Nivel recomendado Punto clave de configuración
Code: cambios diarios Modelo principal de código Debe soportar llamadas a herramientas; ventana de contexto exacta
Architect: diseño de soluciones Modelo de alta capacidad Se puede ampliar el contexto, cuidando el costo
Ask: explicaciones y preguntas Modelo ligero y rápido Sirve un nivel económico cuando no usa herramientas
Debug: diagnóstico Modelo principal o de alta capacidad Deja suficiente longitud de salida para evitar truncamientos
Orchestrator: orquestación de tareas Modelo con llamadas a herramientas estables Configura un modelo de respaldo para cambiar si falla

Conviene asignar un modelo de respaldo a cada modo. Si el principal alcanza su límite o no está disponible, cambiar a uno de respaldo con el mismo protocolo y las mismas capacidades de herramientas es más estable que reintentar repetidamente. La disponibilidad y los precios de los modelos se rigen por la página de precios de modelos.

6. Verifica que la configuración funciona

No basta con ver si el panel responde, porque la respuesta puede venir de otro modo. Verifica en este orden:

  1. Crea una tarea nueva para evitar interferencias del historial.
  2. Selecciona explícitamente el modelo que acabas de configurar; no uses el enrutamiento predeterminado.
  3. Envía una petición corta, por ejemplo, explicar un fragmento de código de menos de diez líneas.
  4. Revisa el registro de peticiones del gateway y confirma que aparece un registro con la misma hora, el mismo modelo y la misma clave.
  5. Pídele después que lea un archivo pequeño para comprobar si la cadena de llamadas a herramientas funciona.
  6. Si no hay registro, la petición no llegó al gateway: vuelve a revisar la Base URL y el proveedor.

Los errores más comunes se interpretan así:

  • Invalid API Key: clave incorrecta, deshabilitada, cuota agotada o campo del proveedor mal rellenado.
  • Model Not Found: ID de modelo mal escrito o modelo no disponible en la cuenta actual.
  • Connection Errors: Base URL inaccesible o problemas de proxy, TLS o firewall.
  • Error de llamada a herramientas: el modelo no soporta llamadas nativas o el gateway solo es compatible con parte del protocolo.
  • Resultado distinto del esperado: confirma primero qué modelo tiene asignado el modo actual y revisa después el prompt y el contexto.

La documentación de ambos proyectos se orienta a diagnosticar por el mensaje de error y no destaca un botón independiente de verificación. La petición real es la confirmación definitiva: guardar correctamente no significa que funcione.

7. Permisos y aprobación automática

Un agente de programación puede leer y escribir archivos y ejecutar comandos, así que los permisos importan más que la elección del modelo. El menú Auto-Approve está junto al cuadro de entrada del chat e incluye el interruptor general Enabled y categorías como Read, Write, Execute, Browser y MCP.

Punto de partida seguro recomendado:

  • Activa primero solo Read y confirma que el alcance de lectura es el esperado.
  • Mantén Write desactivado; actívalo cuando haga falta y configura un retraso de escritura de al menos 1000 milisegundos.
  • Para Execute, usa listas de permitidos y denegados; no abras todos los comandos con *.
  • Desactiva la lectura y escritura fuera del espacio de trabajo y la edición de archivos protegidos.
  • No actives la aprobación automática en repositorios de producción, directorios con secretos o carpetas con datos de clientes.
  • La aprobación automática puede omitir confirmaciones y provocar pérdida de datos o daños en archivos; la ejecución de comandos es especialmente delicada.

El ejemplo de configuración de comandos de la documentación de Roo Code usa el prefijo roo-cline.:

{
  "roo-cline.allowedCommands": ["git status", "npm run", "python -m pytest"],
  "roo-cline.deniedCommands": ["git push", "npm publish", "rm", "sudo"]
}

Zoo Code conserva las costumbres de configuración originales, pero los nombres de las claves y la posición de los menús pueden cambiar; guíate por la página de configuración. La lista de permitidos coincide por prefijo y las reglas de denegación tienen prioridad; los comandos con reemplazos peligrosos se bloquean aunque coincida el prefijo.

8. Lista de seguridad

  • Una clave por uso; no la reutilices entre dispositivos ni entre proyectos.
  • Define límite de cuota y expiración, y rota la clave periódicamente; si sospechas una filtración, deshabilítala primero y luego investiga.
  • No escribas la clave en el código, .env, .vscode/settings.json ni en el historial de commits.
  • Usa .rooignore para excluir .env, credenciales, artefactos de compilación y registros, y reducir las posibilidades de que se lean.
  • No actives la aprobación automática en repositorios que no confías; confirma primero que el espacio de trabajo es de confianza.
  • Revisa los cambios del agente y los comandos de terminal; antes de una operación importante, haz un commit o crea un punto de control.
  • En equipo, pasa siempre por el gateway, da una clave independiente a cada persona y conserva los registros de peticiones para auditoría y para revocar accesos cuando alguien se va.
  • Ten en cuenta que el código y los prompts salen de tu equipo; los equipos con requisitos de retención de datos deben evaluarlo antes.

9. Preguntas frecuentes

¿Roo Code sigue funcionando hoy?

Según el anuncio del repositorio, la extensión Roo Code se suspendió el 15 de mayo de 2026 y el repositorio principal se archivó. La versión instalada puede seguir funcionando, pero no tendrá correcciones ni adaptación a modelos nuevos. Para proyectos nuevos conviene usar directamente la bifurcación comunitaria Zoo Code.

¿Los pasos de configuración de Roo Code y Zoo Code son iguales?

En líneas generales sí: se elige OpenAI Compatible y se rellenan Base URL, clave y modelo. Algunos nombres de menú y claves de configuración pueden variar; guíate por la página de configuración actual y por docs.zoocode.dev.

¿La Base URL debe ser la dirección raíz o terminar en /v1?

Con el protocolo compatible con OpenAI, se escribe hasta /v1, por ejemplo https://ai.zhongshangqihang.com/v1. No incluyas /chat/completions, porque la ruta se duplicaría.

¿Qué hago si aparece Invalid API Key o Model Not Found?

Confirma primero que la clave esté en el formulario de OpenAI Compatible y que la Base URL corresponda al entorno de la clave; después prueba la autenticación con /v1/models. Model Not Found suele deberse a un ID mal escrito o a un modelo no habilitado.

¿Por qué falla la llamada a herramientas?

El proveedor OpenAI Compatible solo admite llamadas nativas, sin respaldo XML. El modelo o el gateway deben soportar function calling compatible con OpenAI; de lo contrario, el chat funciona pero la lectura y escritura de archivos falla. Prueba con otro modelo que soporte herramientas.

Siguiente paso

Regístrate en ZSQH AI Gateway, crea una clave dedicada a Zoo Code y completa la Base URL y el modelo como se explica aquí. Cuando funcionen el chat normal y la lectura de un archivo pequeño, ajusta según precios de modelos el modelo principal y la cuota de cada modo.

Lecturas relacionadas:

Nota: Roo Code es una marca de Roo Code, Inc.; Zoo Code es un proyecto bifurcado de la comunidad; VS Code es una marca de Microsoft Corporation; OpenAI es una marca de OpenAI, Inc. Este artículo solo ofrece una explicación técnica y no implica afiliación ni relación de colaboración con esas entidades. El estado del proyecto, la interfaz y el comportamiento de las interfaces pueden cambiar; consulta los anuncios del repositorio y la documentación del proyecto.