La API Key de Roo Code determina a qué proveedor van las peticiones, qué modelos puedes invocar, a quién se le factura y cuál es el alcance de una filtración. Muchos casos de «la clave no funciona» son en realidad una Base URL, un nombre de modelo o un tipo de proveedor mal elegido.

Este artículo sigue un orden ejecutable: creación, configuración compatible, perfiles multimodelo, seguridad de la clave, rotación, políticas de equipo y diagnóstico. Tras migrar a la bifurcación comunitaria Zoo Code, la mayoría de los conceptos sigue aplicándose.

Nota: Roo Code es una marca de su titular y VS Code es una marca de Microsoft. Este artículo solo ofrece una explicación técnica y no implica afiliación con los fabricantes. La extensión Roo Code dejó de recibir mantenimiento el 15 de mayo de 2026 y el repositorio se archivó ese mismo día; el estado posterior se rige por el repositorio y la documentación oficiales. Modelos y precios se rigen por precios de modelos.

1. Confirma la situación y el tipo de clave

Roo Code es un agente de programación de código abierto para VS Code que usa el modelo BYOK: la extensión no cobra por el modelo y las llamadas se facturan con la clave del proveedor que tú introduces. Admite varios proveedores y también endpoints compatibles con OpenAI.

Conviene aclarar el estado: según la información pública, la extensión Roo Code dejó de recibir mantenimiento el 15 de mayo de 2026, el repositorio original se archivó y desde entonces no hay actualizaciones de funciones, correcciones de errores ni parches de seguridad. Las instalaciones existentes suelen seguir funcionando, pero para el uso a largo plazo hay que incluir en el riesgo la ausencia de parches. La bifurcación comunitaria Zoo Code continúa el desarrollo sobre el código original con licencia Apache-2.0.

«API Key de Roo Code» suele referirse a la clave de un proveedor, a una clave compatible con un gateway o a la configuración de dirección de un modelo local (como Ollama). Este artículo trata el segundo caso: no sirve para iniciar sesión en Roo Code ni para llamar a sus servicios en la nube.

2. Crear la clave: define el alcance antes de copiar

Antes de crearla, decide para quién es, en qué proyecto se usará y cuánto puede gastar como máximo. Esos tres datos determinan si podrás localizar y contener un problema con rapidez.

  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» y pulsa crear.
  3. Pon un nombre que identifique usuario y dispositivo, por ejemplo roo-zhang-macbook; no escribas solo test.
  4. Define límite de cuota y expiración; a las claves de prueba dales primero una cuota baja.
  5. Si la consola permite limitar modelos, marca solo los que vayas a usar.
  6. Copia la clave completa en un gestor de contraseñas; la mayoría de las consolas solo la muestra una vez.

Las claves suelen empezar por sk-, pero el prefijo no demuestra autenticidad ni permisos. Al copiar, revisa espacios y saltos de línea al principio y al final: es una causa frecuente de Invalid API Key.

3. Configurar el endpoint compatible con OpenAI

La ruta es Settings → Providers; elige OpenAI Compatible en API Provider. Solo hay tres campos esenciales:

  • Base URL: escribe una dirección raíz como https://ai.zhongshangqihang.com/v1; no pongas la página de inicio ni llegues hasta /chat/completions.
  • API Key: pega la clave del gateway recién creada.
  • Model: escribe el ID exacto que muestra la página de precios; no adivines sufijos.

Al desplegar Model Configuration también puedes definir Max Output Tokens, Context Window, Image Support, Computer Use, Input Price y Output Price. Los dos últimos solo se usan para estimar el costo localmente y no cambian el cobro real; no infles la ventana de contexto, porque las tareas largas pueden fallar.

Roo Code depende de las llamadas nativas a herramientas del modelo y no tiene respaldo XML. El endpoint compatible no solo debe permitir chat, sino también function calling al estilo OpenAI; de lo contrario, el chat normal funciona y el agente falla en cuanto ejecuta una herramienta.

curl https://ai.zhongshangqihang.com/v1/chat/completions \
  -H "Authorization: Bearer $ZSQH_ROO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<ID del modelo>","messages":[{"role":"user","content":"ping"}],"max_tokens":16}'

Si curl funciona pero Roo Code da error, revisa si la Base URL tiene una ruta de más, si el ID del modelo coincide y si el modelo soporta llamadas a herramientas.

4. API Configuration Profiles: el núcleo del trabajo multimodelo

Los API Configuration Profiles son conjuntos de configuración de modelo que se pueden guardar y cambiar. Cada perfil guarda por separado proveedor, clave, modelo, temperatura, presupuesto de razonamiento, límite de velocidad y ajustes de edición de diferencias. Es la función que más conviene aprender primero para trabajar con varios modelos.

En Settings → Providers, pulsa + junto al selector de perfiles, ponle nombre, elige el proveedor, introduce la clave, selecciona el modelo y configura Rate Limit si hace falta. Rate Limit es el intervalo mínimo entre dos peticiones de ese perfil y está desactivado por defecto. Los perfiles se cambian en el panel de configuración o en el desplegable API Configuration del chat.

El control más fino está en la pestaña Prompts: cada modo puede vincularse a un perfil. Una tarea queda ligada al perfil que tenía al comenzar, y también lo conserva al restaurarse desde el historial; las subtareas del Orchestrator heredan el perfil del padre y lo mantienen durante todo su ciclo de vida. Por eso no conviene vincular el Orchestrator a un modelo caro y esperar después que las subtareas bajen de nivel.

Nombre del perfil Uso Nivel de modelo Estrategia de clave Nota
plan-strong Diseño de arquitectura y refactorización compleja Modelo de razonamiento fuerte Clave independiente, cuota alta Vinculado a Architect
code-daily Programación diaria y corrección de errores Modelo principal Una por persona Vinculado a Code
ask-cheap Preguntas y explicaciones de código Modelo ligero Clave de cuota baja Vinculado a Ask
batch-cheap Cambios masivos de comentarios y formato Modelo económico Clave del proyecto Limitar velocidad
backup Cambio cuando falla el principal Modelo de respaldo Clave independiente Verificar periódicamente

Se recomienda nombrarlos como «escenario-nivel» para facilitar la revisión. Los ID de modelo y los precios cambian; guíate por precios de modelos.

5. Seguridad de la clave: almacenamiento, permisos y límites de datos

Según la documentación, la clave se guarda en Secret Storage de VS Code y no se escribe en texto plano en los archivos de configuración normales. Pero eso no equivale a seguridad absoluta: la protección depende de la cuenta del sistema operativo, y quien pueda iniciar sesión en tu equipo o un proceso con tus permisos todavía podría acceder a ella.

Por eso hay que hacer más cosas: usa una cuenta de sistema independiente en el equipo de desarrollo y no guardes claves de forma permanente en equipos compartidos; define una lista blanca de extensiones en los dispositivos de la empresa; confirma el alcance de la sincronización de configuración y no sincronices ajustes sensibles a dispositivos no controlados; no pegues la clave en prompts, comentarios de código ni en el historial de terminal; tapa los campos de clave antes de hacer capturas; y elige el canal según la clasificación de los datos, porque el contexto del código se envía al servicio indicado por la Base URL.

El objetivo del mínimo privilegio es que «aunque haya filtración, la pérdida tenga un techo»: define cuota, expiración y lista blanca de modelos; si el gateway admite listas de IP o ámbitos de proyecto, actívalas también. Separa las claves de prueba, de uso diario y de automatización; no uses una sola para todo.

6. Rotación, revocación y respuesta a incidentes

Se recomienda rotar cada 90 días, o de inmediato cuando alguien deja el equipo, se pierde un dispositivo o se sospecha una filtración. Como Roo Code ya no recibe mantenimiento, las versiones antiguas no obtienen parches de seguridad y el periodo puede ser más conservador.

El orden seguro es «primero en paralelo, luego el cambio, después la desactivación»: crea una clave nueva con sufijo de fecha; guárdala en el gestor de contraseñas y conserva temporalmente la anterior; sustitúyela en el perfil y prueba; confirma que el registro del gateway muestra la clave nueva; observa la tasa de errores uno o dos días; y por último desactiva la clave antigua.

Si confirmas una filtración, invierte el orden: desactiva o elimina primero la clave, revisa después el consumo anómalo, el origen y el periodo, y examina luego el historial del repositorio, los registros y el historial de chat. Prioriza contener la pérdida; no empieces por reconstruir la ruta de la filtración.

7. Uso en equipo: convertir la configuración personal en política

Las claves de Roo Code viven en cada equipo de desarrollo; si un equipo depende solo de la extensión, es difícil ver de forma centralizada quién usa qué clave. El control centralizado debe estar en el gateway: una clave por persona, claves por proyecto, cuota unificada y registro de peticiones.

  • Claves nominales: el nombre incluye miembro y uso; se desactivan el día que la persona se va y no se comparte una «clave de equipo».
  • Aislamiento por proyecto: claves independientes y cuotas separadas para producción, experimentación y automatización.
  • Espacios de trabajo sin secretos: el repositorio solo contiene Base URL, nombres de modelo y descripción de modos; la clave queda en el almacenamiento del usuario.
  • Servicios compartidos con cuenta propia: CI, scripts y bots usan claves de servicio, sin mezclarse con las de las personas.
  • Auditoría mensual: revisa claves sin uso prolongado, cuotas anómalas y aumentos repentinos de fallos de autenticación.
  • Mínimo privilegio: no asignes modelos potentes a escenarios ligeros ni permitas la ejecución automática de comandos en tareas de solo lectura.

La aprobación automática mejora la eficiencia, pero también amplifica los errores y el consumo de tokens; el equipo debe definir qué comandos requieren confirmación manual.

8. Diagnóstico de fallos frecuentes

  • Invalid API Key: clave incompleta, con espacios o introducida en un proveedor específico de Anthropic o Gemini. Cambia a OpenAI Compatible y reintenta.
  • Model Not Found / 404: ID de modelo mal escrito o Base URL con /chat/completions de más. Copia el ID tal cual de la página de precios y deja la Base URL solo hasta /v1.
  • 401 / 403: clave desactivada, cuota agotada o sin permiso para el modelo. Revisa primero el estado y el consumo en la consola.
  • 429: límite de velocidad o de cuota alcanzado. Reduce la concurrencia y revisa Rate Limit y el límite de la clave.
  • El chat funciona pero falla la llamada a herramientas: el endpoint o el modelo no soportan function calling nativo. Cambia a un modelo o endpoint que sí lo soporte.
  • Una tarea larga falla a mitad: ventana de contexto inflada o límite de salida poco razonable. Escribe los valores reales.

El diagnóstico debe seguir tres capas: revisar proveedor, Base URL y nombre de modelo; reproducir con curl; comprobar si el registro del gateway tiene la petición correspondiente. Si las tres capas coinciden, el problema normalmente no está en la clave.

Preguntas frecuentes

¿Roo Code sigue funcionando hoy?

La extensión instalada suele seguir funcionando, pero el equipo original dejó de mantenerla el 15 de mayo de 2026, el repositorio se archivó y ya no hay actualizaciones ni parches de seguridad. Para proyectos nuevos conviene evaluar Zoo Code u otras herramientas que sigan recibiendo mantenimiento; si continúas con la versión antigua, limita los permisos de la clave.

¿Dónde se guarda la clave?

Según la documentación, en Secret Storage de VS Code, no en texto plano dentro de los archivos de configuración normales. Sigue siendo una credencial del equipo local, y su nivel de protección depende de la cuenta del sistema y de la seguridad del equipo de desarrollo. En dispositivos compartidos usa una cuenta independiente y evita sincronizar configuraciones sensibles.

¿Puedo usar una clave en varios perfiles?

Sí, pero no es recomendable. Cada perfil corresponde a modelos y cuotas distintos; separar las claves permite ver en los registros quién la usa y para qué, y también acota el alcance de un problema.

¿Por qué el chat normal funciona y el agente falla?

Roo Code solo usa llamadas nativas a herramientas, sin respaldo XML. El endpoint compatible debe implementar function calling al estilo OpenAI y el modelo también debe soportarlo. Prueba primero con un modelo que soporte herramientas y después decide si el problema está en el endpoint o en el modelo.

¿El equipo debería compartir una sola clave?

No es recomendable. Una clave compartida impide distinguir el consumo y complica la revocación cuando alguien se va. Debe haber una clave por persona, claves separadas para CI o servicios compartidos, y cuotas y alertas unificadas en el gateway.

Resumen

Si todavía usas Roo Code o Zoo Code, crea primero una clave de prueba con cuota baja, valídala con curl y con una tarea real del agente, y distribúyela después al equipo. Puedes empezar por el registro; los modelos, las cuotas y la facturación están en precios de modelos, y los precios cambian según la versión del modelo y la política del proveedor.

Lecturas relacionadas:

Nota: Roo Code, Cursor, Claude Code, Anthropic y OpenAI son marcas o marcas registradas de sus respectivos titulares. Este artículo solo ofrece una explicación técnica y no implica afiliación ni relación de colaboración con esas empresas. El comportamiento de la extensión y de las interfaces puede cambiar según la versión; consulta la documentación oficial y los anuncios del repositorio.