¿OpenBot no se conecta a APIYI? Con 3 variables de entorno, tu compañero de IA enciende el ordenador por sí solo

Nota del autor: OpenBot no tiene una interfaz para «elegir modelo». El modelo se configura en .env y en el archivo model.yaml del paquete de inquilino. En este artículo veremos cómo conectar APIYI cambiando tres variables de entorno y una línea de YAML, habilitar primero solo 3 herramientas de computadora y verificar que todo funciona con una prueba: «abrir una página web + leer un archivo + revisar la auditoría».

Clonas OpenBot de CopilotKit, abres .env.example y buscas por toda la interfaz, pero no encuentras ningún desplegable para «elegir proveedor de modelos». No tienes una tarjeta aceptada por OpenAI y solo quieres usar APIYI con pago por uso para ejecutar claude-opus-5-5, pero ni siquiera sabes dónde se configura el modelo.

La respuesta corta es esta: OpenBot no tiene un selector de modelos. El modelo se configura en .env y en el archivo model.yaml del paquete de inquilino. Para conectar APIYI no necesitas cambiar código: basta con modificar tres variables de entorno y una línea de YAML. Después, habilita solo 3 herramientas de computadora y, una vez que hayas comprobado que funcionan, activa las demás según las necesites.

Este no es un tutorial para poner todo en marcha con un solo clic. OpenBot es una plantilla y, para ejecutarla, necesitas Docker, Bun 1.4+, un proyecto de CopilotKit Intelligence y una clave API para el modelo. Aquí explicaremos todos estos requisitos. Además, hay dos proyectos llamados OpenBot en GitHub; este artículo trata sobre el de CopilotKit.

Qué conseguirás: al terminar, sabrás ajustar la configuración, empezar con 3 herramientas y realizar una prueba verificable de «abrir una página web + leer un archivo + revisar la auditoría». También encontrarás una tabla para resolver problemas frecuentes, como errores 400 o 401, modelos que no existen, herramientas que no se invocan o un inicio rechazado.

El modelo de OpenBot no se configura en la interfaz

OpenBot es una plantilla, no un producto

CopilotKit/OpenBot es un repositorio de código abierto con licencia MIT, creado el 17 de agosto de 2026. Al 2 de noviembre de 2026, el repositorio tenía 9.561 estrellas, su última versión oficial era la v0.2.0 (12 de octubre de 2026) y la parte superior del README seguía indicando que estaba en beta. Su propuesta es que cada compañero de IA —llamado Bot en el repositorio— tenga su propia computadora, con un navegador real, sus propias sesiones iniciadas, sus archivos y las herramientas que se le hayan concedido.

El README lo dice sin rodeos: es «una plantilla, no un producto». No tiene una versión alojada en la que puedas registrarte ni se distribuye como paquete de dependencias. La forma de usarlo es clonar el repositorio, sustituir los paquetes de ejemplo de examples/ por tus propios compañeros, canales y habilidades, y ejecutarlo por tu cuenta. Así que la respuesta a «¿dónde se elige el modelo?» está en los archivos de configuración, no en la interfaz.

Cuatro requisitos para poner OpenBot en marcha

La siguiente tabla recoge lo que necesitas preparar antes de conectar un modelo. Si falta cualquiera de estos elementos, no podrás verificar la configuración posterior.

Requisito	Qué necesitas	Detalles
Docker	Para ejecutar PostgreSQL (con pgvector) y los Bots incluidos	`scripts/start.sh` inicia los servicios de Docker y ejecuta las migraciones
Bun	Versión 1.4 o superior	Instala las dependencias con `bun install`
CopilotKit Intelligence	Un proyecto y una licencia; hay un plan gratuito	El entorno de evaluación local utiliza macOS + Docker Desktop. La licencia local dura 30 días y se puede renovar con `npx copilotkit@latest local renew`
Clave del modelo	Una clave para un endpoint compatible con OpenAI	En este artículo usamos un token de APIYI, con `https://api.apiyi.com/v1` como base_url

Es fácil subestimar el requisito de Intelligence. Los comentarios de .env.example aclaran que, si faltan la URL de Intelligence, la URL del gateway o la clave, el servidor se negará a arrancar. El texto original lo resume así: «There is no degraded mode» —no hay modo degradado—. La razón es que Intelligence se encarga de los hilos persistentes y la memoria; sin él, se perdería el contexto de cada conversación. Por eso no se puede describir OpenBot como una solución «completamente desconectada».

OPENAI_BASE_URL afecta a todo el despliegue

El README indica que ningún modelo viene incluido: las credenciales las proporciona el administrador, se guardan cifradas en la base de datos y no aparecen en los logs. El modelo se determina mediante variables de entorno del despliegue. La más importante es OPENAI_BASE_URL, que, según la documentación oficial, puede apuntar a cualquier endpoint que use la misma API, incluidos gateways de varios proveedores, proxies o modelos ejecutados en tu propio hardware. Los comentarios de .env.example son más concretos: sirve cualquier endpoint compatible con /v1/chat/completions.

Esta variable afecta a todo el despliegue, no a un solo Bot. La leen el cliente que usa el API server para el agente integrado, agent-bot cuando construye su propio cliente y agent-langgraph cuando usa BOT_PROVIDER=openai. Según la documentación oficial, la ventaja es que evita que, dentro de un mismo despliegue, la mitad de las solicitudes apunten a la dirección nueva y la otra mitad sigan usando la anterior.

Conecta OpenBot con APIYI con tres cambios: configuración de las variables de entorno

Cómo se conectan OpenBot y APIYI

APIYI ofrece una interfaz compatible con OpenAI. Configura base_url como https://api.apiyi.com/v1 y las solicitudes pasarán por /v1/chat/completions, justo lo que requiere OpenBot para OPENAI_BASE_URL. Hay otro detalle importante: OpenBot transmite el nombre del modelo tal cual (verbatim), y /v1/models de APIYI devuelve el nombre sin prefijo, claude-opus-5-5. Por eso, no añadas el prefijo openai/ que aparece en el ejemplo del gateway oficial. El ejemplo oficial openai/gpt-5.6-terra solo se aplica a endpoints que añaden un espacio de nombres al modelo.

Primero, una tabla general; después, los pasos de configuración.

Dónde cambiarlo	Nuevo valor	Por qué
`OPENAI_API_KEY` en `.env`	El token `sk-...` que creaste en la consola de APIYI	El agente integrado y los dos bots incluidos usan esta clave de forma predeterminada
`OPENAI_BASE_URL` en `.env`	`https://api.apiyi.com/v1`	Dirige las solicitudes a modelos de todo el despliegue al endpoint compatible de APIYI
`BOT_MODEL` en `.env`	`claude-opus-5-5`	Indica qué modelo usará el bot al iniciarse; si se deja vacío, se usa el valor del archivo de especificación del proveedor
`default_model` en `examples/<tu-paquete>/model.yaml`	`claude-opus-5-5`	El paquete de ejemplo usa actualmente `gpt-5.6-terra`; si no lo cambias, aparecerá un error de modelo inexistente
`BOT_RESPONSES_API` en `.env`	Mantener `false`	Claude devuelve un error 400 en el endpoint Responses de APIYI

Paso 1: crea un token dedicado

En la página de tokens de APIYI, api.apiyi.com/token, crea una clave, establece un límite de saldo y una fecha de vencimiento, e indica como uso «Evaluación local de OpenBot».
Desde tu equipo, envía con curl una petición GET https://api.apiyi.com/v1/models con el encabezado Authorization: Bearer sk-....

Criterio de verificación: la respuesta debe ser HTTP 200 y la lista debe incluir claude-opus-5-5. Probamos este paso el 2026-11-02 y obtuvimos 259 modelos, entre ellos claude-opus-5-5 y claude-opus-5-5-thinking.

Crear un token aparte permite separar el uso exclusivo de este equipo del uso en producción. Durante la fase de plantilla, Bot hará muchas pruebas; contar con un límite de saldo ayuda a mantener el gasto bajo control.

Paso 2: modifica tres líneas de .env

Según la guía oficial de inicio rápido, ejecuta primero cp .env.example .env y bun install. Después, ejecuta en orden npx --yes copilotkit@latest login, npx --yes copilotkit@latest project select y bun scripts/setup-learning.ts para guardar la clave de runtime y el contenedor de Learning en .env. Luego modifica estas tres líneas:

OPENAI_API_KEY=sk-tu-token-de-APIYI
OPENAI_BASE_URL=https://api.apiyi.com/v1
BOT_MODEL=claude-opus-5-5

Comprueba también cuatro cosas: BOT_PROVIDER debe conservar su valor predeterminado, openai; BOT_RESPONSES_API debe seguir en false; genera KEY_ENCRYPTION_KEY con openssl rand -base64 32; y ten en cuenta que AGENT_BOT_MODEL solo lo utiliza agent-bot para la prueba de concepto. Su valor predeterminado es gpt-5.5 y es independiente de BOT_MODEL. Si también vas a iniciar agent-bot, comprueba que ese nombre aparezca en /v1/models o cámbialo por el modelo que quieras usar.

Criterio de verificación: la clave y la dirección que muestra grep OPENAI_ .env son correctas, y la dirección termina en /v1, sin barras ni espacios adicionales. Si el contenedor necesita una ruta distinta para acceder al mismo endpoint, puedes sobrescribirla con OPENAI_CONTAINER_BASE_URL. Sin embargo, como APIYI tiene una dirección pública, normalmente no necesitarás esta variable.

Tercer paso: cambia una línea de model.yaml en el paquete del tenant

Abre examples/fintech/model.yaml o la copia del paquete del tenant que hayas creado. La configuración actual contiene model.provider: openai, model.credential_secret_ref: openai-api-key y model.default_model: gpt-5.6-terra.

Cambia default_model a claude-opus-5-5.
Mantén provider como openai. La documentación oficial indica que aquí solo se acepta openai o anthropic. Para usar el endpoint compatible con OpenAI de APIYI, selecciona openai.
No sustituyas credential_secret_ref por una clave en texto plano: este campo hace referencia a una credencial ya almacenada.

Criterio de aceptación: después de ejecutar bash scripts/start.sh, todas las comprobaciones de salud pasan y, al abrir http://localhost:3010, aparecen los dos compañeros predeterminados: General Assistant y Knowledge.

Hay un detalle importante que conviene tener en cuenta. Al iniciar, el servidor normalmente pregunta a OpenAI o Anthropic si la clave puede acceder a default_model. Si no puede, muestra model-unavailable o model-credential-rejected. Pero si se configura OPENAI_BASE_URL, esta comprobación se omite. Por eso, al conectar APIYI, un error en el nombre del modelo no aparecerá durante el arranque, sino al enviar el primer mensaje. Que el servicio arranque correctamente solo significa que está en marcha, no que el modelo esté bien configurado.

Sobre las versiones: diferencias entre v0.2.0 y la rama main

Es importante dejar esto claro. En la sección Unreleased del CHANGELOG de la rama main hay un cambio: cuando los modelos openai/... del bot integrado usan un OPENAI_BASE_URL que no es ni de OpenAI ni de Azure, pasan a llamar a /chat/completions de ese endpoint en lugar de usar la API de Responses. El motivo, según el proyecto, es que la mayoría de los endpoints compatibles con OpenAI solo ofrecen Chat Completions. El mismo cambio también añade COPILOTKIT_OPENAI_API=responses|chat para forzar una de las dos opciones.

Este cambio todavía no está incluido en la etiqueta oficial v0.2.0. Si tienes instalada la versión v0.2.0, es posible que el bot integrado siga llamando a Responses cuando utiliza una URL base de terceros. A la luz de las pruebas que veremos más adelante, esta es una causa probable del error 400. Hay dos formas de abordarlo: evaluar la integración con la rama main, teniendo en cuenta que sigue cambiando, o esperar a que el cambio se incluya en una versión oficial.

🚀 Inicio rápido: antes de configurar OpenBot, te recomendamos probar por separado /v1/chat/completions con un token de APIYI apiyi.com. Incluye una definición de función y comprueba que finish_reason devuelva tool_calls. Una vez confirmado que la interfaz funciona correctamente, podrás centrarte en la configuración de OpenBot si surge algún problema.

Permite solo 3 herramientas al principio: limita los permisos de OpenBot

Por qué no conviene habilitarlo todo desde el inicio

La documentación oficial resume así el problema de la cantidad de herramientas: «Un modelo elige la herramienta correcta de forma fiable entre unas diez, pero no entre treinta». Es decir, con alrededor de diez herramientas puede elegir bien de forma consistente; con treinta, deja de ser fiable. El código fuente de OpenBot registra trece herramientas de computadora y, si sumas las del catálogo MCP, es fácil superar ese límite desde el primer día.

Cuando un Bot tiene más de doce herramientas, en cada ejecución solo recibe las que necesita la skill que coincide con el mensaje actual. Pero la documentación oficial aclara que esto solo reduce lo que el modelo puede ver: «No es una barrera de seguridad y nunca la sustituye». Las barreras reales son tres: los permisos (grant) otorgados a cada Bot en Admin, la política de acciones AGENT_COMPUTER_POLICY y los registros de auditoría. Ten en cuenta, además, que la configuración predeterminada al iniciar es deny: [] y allow: ["true"], lo que equivale a permitirlo todo.

Las 3 herramientas para empezar

Herramienta	Función	Al empezar
`computer_navigate`	Abrir una URL en el navegador	✅ Permitir
`computer_snapshot`	Obtener una instantánea de la página	✅ Permitir
`computer_read_file`	Leer archivos del espacio de trabajo	✅ Permitir
`computer_click` / `computer_type` / `computer_key`	Hacer clic, escribir y pulsar teclas	⏸ Habilitar según sea necesario tras la validación
`computer_write_file`	Escribir archivos	⏸ Habilitar según sea necesario tras la validación
`computer_run_command`	Ejecutar comandos de shell	⛔ Denegar explícitamente

Hay que bloquear computer_run_command por separado. Al activar COMPUTER_SEPARATE_WORKSPACES con Compose, cada Bot inicia una shell en su propia carpeta, pero la documentación oficial reconoce que «los comandos aún pueden leer otras carpetas». Para conseguir un aislamiento real, necesitas computers.mode: sandbox. Al empezar, no hace falta asumir ese riesgo.

Configura AGENT_COMPUTER_POLICY

La política es un objeto JSON cuyas reglas usan expresiones CEL y pueden leer campos como tool.name, page.host y file.path. Para empezar, puedes configurarla así:

Escribe una línea en .env: AGENT_COMPUTER_POLICY={"mode":"enforce","deny":["tool.name == 'computer_run_command'"],"allow":["tool.name in ['computer_navigate','computer_snapshot','computer_read_file']"]}
En Admin, concede a General Assistant acceso a esas tres herramientas y a ninguna más.
Reinicia el servicio. Si el formato JSON es incorrecto, el servidor no arrancará, lo que facilita detectar el problema.

Hay dos reglas de evaluación que conviene conocer. Primero, deny tiene prioridad sobre allow, así que la shell seguirá bloqueada aunque más adelante amplíes los permisos de allow. Segundo, el motor falla en modo cerrado: si la política falta o está vacía, no se permite nada; si una regla deny está mal escrita, se deniega la acción; si una regla allow está mal escrita, no se concede el permiso. El principio es sencillo: restringe primero y amplía los permisos según sea necesario. Una vez superada la validación, incorpora las funciones de clic, escritura o creación de archivos de una en una y revisa la auditoría después de cada cambio.

Validación y solución de problemas de OpenBot con APIYI

Una prueba verificable: abrir una página, leer un archivo y revisar la auditoría

Según la arquitectura oficial, una llamada a una herramienta sigue este orden: se resuelve el destino, se evalúa según la política vigente, se escribe un registro de auditoría y solo entonces se ejecuta la acción en el equipo. Si la acción enviada falla, se escribe un segundo registro. El equipo en sí no toma decisiones sobre políticas: ese control está en el gateway del servidor. Por eso, la validación debe comprobar tanto que las acciones funcionan como que quedan registradas:

Crea un archivo notes.md en /workspace y escribe un par de líneas.
Pídele a General Assistant que abra una página web pública, te diga el título y después lea el contenido de /workspace/notes.md.
Pídele después que ejecute ls /. La solicitud debería rechazarse y la respuesta debería indicar qué regla la bloqueó.
Abre la página Audit y comprueba que aparecen los registros de autorización de navigate, snapshot y read_file, así como el registro de rechazo de run_command. Si necesitas exportarlos, puedes llamar a GET /api/admin/audit-events?format=csv, con un máximo de 5.000 filas por solicitud.

En cuanto a la disponibilidad del modelo, solo la hemos probado en APIYI. El 2026-11-02, llamamos a /v1/chat/completions con claude-opus-5-5 y una definición de función read_file. La respuesta fue HTTP 200 en 4,06 segundos, con finish_reason igual a tool_calls y los argumentos {"path":"/workspace/notes.md"}. El consumo fue de 393 tokens de prompt y 55 tokens de completion. Al añadir stream: true, también recibimos un 200: en los fragmentos SSE se veía la salida incremental del nombre de la función y sus argumentos, y la respuesta terminaba con data: [DONE]. Esto demuestra que el endpoint de chat de APIYI puede devolver las llamadas a herramientas de Claude en formato OpenAI, justo lo que necesita un agente en el que el modelo solo decide qué función llamar y no se encarga de ejecutarla.

Tabla de diagnóstico: cinco errores comunes

Problema	Causa más probable	Solución
400 `field messages is required`	La solicitud llegó al endpoint Responses. En nuestras pruebas, `claude-opus-5-5` devuelve este error al llamar a `/v1/responses` de APIYI	Comprueba que `BOT_RESPONSES_API=false`. Si usas la versión v0.2.0, es posible que el Bot integrado siga llamando a Responses. Puedes usar la rama main y configurar `COPILOTKIT_OPENAI_API=chat` (todavía no publicado)
401	La clave es incorrecta, caducó o se agotó el saldo disponible del token	Vuelve a la página de tokens de APIYI, comprueba la fecha de vencimiento y el saldo, y prueba de nuevo `/v1/models` con curl
El modelo no existe	`default_model` sigue configurado como `gpt-5.6-terra`, o se añadió `openai/` delante del nombre	Escribe el nombre sin prefijos, `claude-opus-5-5`, en ambos lugares. Como se omite la comprobación de inicio, tendrás que enviar un mensaje para verificarlo
No se llamó a la herramienta	El modelo no admite llamadas a herramientas, no se concedió el permiso o alguna política bloqueó la herramienta	Según la documentación oficial, un Bot sin llamadas a herramientas no puede controlar la computadora. Revisa primero si hay registros de rechazo en la auditoría
Se rechazó el inicio	Falta la configuración de Intelligence, hay un error en el JSON de la política o se añadió un proveedor en la especificación de proveedores sin actualizar `PROVIDER_IDS`	Completa los tres campos de Intelligence y valida el JSON. Para conectar APIYI no necesitas añadir un proveedor: basta con mantener `openai`

💡 Consejo de diagnóstico: Si aparece un error, envía primero la misma solicitud directamente a /v1/chat/completions de APIYI, en apiyi.com. Si la conexión directa funciona pero falla en OpenBot, el problema está en la configuración o la versión de OpenBot. Si también falla la conexión directa, revisa el token y el modelo. Así puedes reducir a la mitad las posibles causas.

Coste orientativo de usar Claude con OpenBot

APIYI cobra por consumo, sin cuota mensual fija. Estos son los precios de claude-opus-5-5 consultados el 2026-11-02; claude-opus-5-5-thinking tiene el mismo precio:

Concepto	Precio por millón de tokens
Entrada	$4
Salida	$20
Lectura de caché	$0.2

Consulta la lista de modelos de la plataforma para conocer los modelos y precios vigentes. En nuestra prueba con herramientas, la solicitud usó 393 tokens de entrada y 55 de salida, así que el coste fue muy bajo. Pero, cuando el Bot empieza a navegar y leer archivos durante varios turnos, el contexto crece rápido. Por eso, conviene establecer también un límite de saldo para el token.

Preguntas frecuentes

Q1: ¿Hay que modificar el código fuente para conectar OpenBot a APIYI?

No. Basta con cambiar las tres líneas `OPENAI_API_KEY`, `OPENAI_BASE_URL` y `BOT_MODEL` en `.env`, y modificar `default_model` en el archivo `model.yaml` del paquete de inquilino. Solo hay que cambiar la especificación del proveedor y `PROVIDER_IDS` cuando se añade un tipo de proveedor completamente nuevo. APIYI usa una interfaz compatible con OpenAI, así que no es el caso.

Q2: ¿Por qué no usar un nombre con prefijo como openai/claude-opus-5-5?

OpenBot transmite el nombre del modelo tal cual, por lo que debes usar el nombre publicado por el propio endpoint. El endpoint `/v1/models` de APIYI, apiyi.com, muestra el nombre sin prefijo: `claude-opus-5-5`. Si añades el prefijo, no encontrará el modelo.

Q3: ¿Se puede activar BOT_RESPONSES_API para usar Responses API?

No lo actives al conectar Claude. En nuestras pruebas, `claude-opus-5-5` devolvió un error 400 `field messages is required` al llamar a `/v1/responses` de APIYI; al cambiar a `gpt-5.4-mini`, devolvió 200. La documentación oficial también indica que esta opción solo debe activarse si el endpoint implementa realmente Responses API.

Q4: ¿Pusieron en marcha OpenBot completo?

No. Solo verificamos la parte de APIYI: la lista de modelos, una llamada de chat con herramientas, la salida en streaming y el error del endpoint Responses. No ejecutamos OpenBot completo —Docker más el proyecto Intelligence— en el equipo donde redactamos el artículo. Las explicaciones sobre su funcionamiento interno se basan en el repositorio y la documentación oficiales.

Q5: ¿Cómo evitar que el Bot se exceda con una clave de pago por consumo?

En la página de tokens de APIYI, apiyi.com, establece un límite de saldo y una fecha de caducidad para esa clave, y gestiónala por separado de las claves de producción. Si además aplicas la estrategia de tres herramientas de este artículo, limitarás tanto lo que puede hacer el Bot como lo que puede gastar.

Resumen

Puntos clave para conectar OpenBot con APIYI

El modelo no se configura en la interfaz: se define en tres líneas de .env y una línea de model.yaml del paquete del inquilino.
base_url afecta a toda la implementación: al cambiar OPENAI_BASE_URL, los tres tipos de Bot cambian a la vez.
Que arranque no garantiza que el modelo sea correcto: al conectarlo a una pasarela, se omite la comprobación. Hay que enviar el primer mensaje para verificarlo.
Revisa la versión: el cambio para usar /chat/completions sigue como Unreleased en la rama main y aún no forma parte de v0.2.0.
Empieza con solo 3 herramientas: deny tiene prioridad sobre allow; rechaza shell por separado y amplía los permisos poco a poco.
Empieza con APIYI y pago por uso: usa un token dedicado con un límite de saldo y escribe claude-opus-5-5 sin prefijos.

La configuración del modelo en OpenBot puede ser difícil de encontrar porque no está en la interfaz. Ajusta estas tres cosas: las tres líneas de .env, una línea de model.yaml y mantén Responses desactivado. Después, empieza con una política que permita solo 3 herramientas. Así tendrás clara toda la cadena de configuración. Para verificarla, comprueba solo tres cosas: que se pueda abrir una página web, leer un archivo y que las acciones rechazadas queden registradas en la auditoría.

Te recomendamos probar primero el chat con llamadas a herramientas usando un token dedicado de APIYI en apiyi.com y, después, conectarlo a OpenBot. Así, si surge algún problema, podrás identificar rápidamente de qué lado está la causa.

📚 Referencias

Repositorio de CopilotKit/OpenBot: README, Requirements y Quick start
Enlace: github.com/CopilotKit/OpenBot
Descripción: propósito de la plantilla, requisitos previos e información de la versión v0.2.0
Documentación de configuración de OpenBot: variables de entorno del modelo, model.yaml y validación al iniciar
Enlace: github.com/CopilotKit/OpenBot/blob/main/docs/configuration.md
Descripción: definiciones originales de OPENAI_BASE_URL, BOT_MODEL y BOT_RESPONSES_API
Documentación de arquitectura de OpenBot: gateway, políticas y auditoría
Enlace: github.com/CopilotKit/OpenBot/blob/main/docs/architecture.md
Descripción: orden de invocación de herramientas e interfaz de exportación de auditoría
Centro de documentación de APIYI: modo compatible con OpenAI, llamada a funciones y lista de modelos
Enlace: docs.apiyi.com
Descripción: formato de base_url, formato de tools y precio de claude-opus-5-5

Autor: Equipo técnico de APIYI
Contacto técnico: Puedes contactarnos en el sitio oficial de APIYI, apiyi.com. Para más información sobre la integración, visita el centro de documentación en docs.apiyi.com.

¿OpenBot no se conecta a APIYI? Con 3 variables de entorno, tu compañero de IA enciende el ordenador por sí solo