Cline en producción: configurar sesiones y recuperarse de forma segura
Guía práctica para configurar las sesiones de ClineCore, separar los ajustes del entorno de ejecución de la configuración del proveedor y diseñar reglas seguras de reintento y recuperación.
Resumen · TL;DR
ClineCore separa las opciones del entorno de ejecución —como el modo de backend, las capacidades, las políticas de herramientas y la automatización— del proveedor y el modelo configurados para cada sesión. Esta guía explica cómo hacer explícita esa separación y diseñar la recuperación en torno a los ID de sesión y el estado persistido, en lugar de repetir el trabajo a ciegas.
Puntos clave
- Mantén como decisiones separadas la configuración del entorno de ejecución, los permisos de herramientas y la configuración del proveedor y el modelo.
- Usa los ID de sesión y los mensajes persistidos para investigar los fallos antes de volver a intentarlo.
- Considera que los reintentos pueden duplicar efectos secundarios; define puntos de control y reglas de recuperación para tu flujo de trabajo.
- La referencia de la API documenta las operaciones de sesión, pero no especifica la semántica de los reintentos, los formatos de punto de control ni garantías de compatibilidad con proveedores.
En esta página (9)
ClineCore permite que una aplicación controle la creación de sesiones, la selección del entorno de ejecución, los permisos de herramientas y el historial de las sesiones. En las operaciones de flujos de trabajo de producción, la decisión de diseño clave no consiste simplemente en determinar si se debe reintentar una llamada fallida, sino en averiguar qué ocurrió antes de volver a ejecutar el trabajo.
La configuración siguiente es ilustrativa; no es una receta de despliegue probada. La referencia de la API de ClineCore documenta las opciones y los métodos que se tratan aquí. Consulta la versión del SDK que instales para conocer los tipos y el comportamiento exactos.
Separa la configuración del entorno de ejecución de la del modelo
Un límite útil entre configuraciones consta de tres partes:
- Entorno de ejecución: selección del backend, identidad del cliente y ajustes opcionales de conexión remota o al hub.
- Política de ejecución: políticas de herramientas, capacidades y si las API de automatización están habilitadas.
- Configuración del modelo de la sesión: ID del proveedor, ID del modelo, credenciales, rutas del espacio de trabajo y disponibilidad de herramientas para una sesión determinada.
Esta separación facilita gestionar la política del entorno de ejecución con independencia de los cambios de modelo. No hace que los campos específicos del proveedor sean intercambiables: providerId, modelId y apiKey siguen teniendo que ser válidos para el proveedor seleccionado. La referencia de la API no garantiza la compatibilidad con todos los proveedores ni con todos los endpoints.
Crea un entorno de ejecución e inicia una sesión
Requisitos previos: instala la versión del SDK de Cline que quieras desplegar, proporciona credenciales mediante el método de gestión de secretos de tu aplicación y decide qué herramientas puede utilizar el agente. No incluyas credenciales en los registros ni en los metadatos de sesión.
import { ClineCore } from "@cline/sdk"
const cline = await ClineCore.create({
clientName: "repo-maintenance-worker",
backendMode: "auto",
toolPolicies: {},
automation: false,
})
const session = await cline.start({
prompt: "Inspect the repository and report failing tests. Do not modify files.",
source: "scheduled-check",
interactive: false,
sessionMetadata: { jobId: "job-123" },
config: {
providerId: "anthropic",
modelId: "claude-sonnet-4-6",
apiKey: process.env.ANTHROPIC_API_KEY,
systemPrompt: "Follow the task scope and report actions taken.",
cwd: process.cwd(),
workspaceRoot: process.cwd(),
enableTools: true,
enableSpawnAgent: false,
enableAgentTeams: false,
},
})
console.log(session.sessionId)
Los valores de proveedor y modelo anteriores reflejan el ejemplo de la referencia de la API; no constituyen una recomendación ni una afirmación de compatibilidad con proveedores más allá de ese ejemplo. La referencia documenta los valores de backendMode auto, local, hub y remote, además de los ajustes opcionales hub y remote. No establece qué modo conviene más para un despliegue determinado. Elige de forma deliberada y valida la conectividad y los permisos en tu entorno.
Un objeto toolPolicies vacío no es una política de seguridad. Establece valores predeterminados explícitos y políticas por sesión según los tipos de política compatibles con el SDK instalado. Usa capabilities cuando el cliente proporcione ejecutores de herramientas o funciones de aprobación, y comprueba que las acciones restringidas se denieguen realmente.
Diseña reglas de reintento en torno al estado de la sesión
Un error de red o el tiempo de espera agotado de un proceso de trabajo no demuestra que el agente haya dejado de trabajar antes de completar la tarea. Repetir la solicitud original puede duplicar ediciones, llamadas externas u otros efectos secundarios. La referencia de la API enumera get, readMessages, getAccumulatedUsage, abort, stop y restore, pero no especifica reintentos automáticos, ejecución exactamente una vez ni el contenido de un punto de control.
Una secuencia operativa más segura sería:
- Registra el ID de sesión de inmediato. Persístelo junto con el identificador del trabajo para que un proceso reiniciado pueda localizar la misma sesión.
- Clasifica el fallo. Distingue un fallo terminal confirmado de un tiempo de espera agotado o una conexión perdida cuyo resultado sea incierto.
- Inspecciona antes de volver a enviar. Usa
getyreadMessagespara revisar los metadatos de la sesión y los mensajes persistidos. Cuando corresponda, consulta el uso acumulado como indicio operativo, no como prueba de que se haya completado una acción concreta. - Elige cómo recuperarte de forma deliberada. Si la sesión sigue activa, decide si esperas, la cancelas con
aborto la detienes constop. Si el trabajo debe continuar,sendacepta un ID de sesión y una solicitud de seguimiento. Si hay un punto de control disponible y adecuado, la API ofrecerestore; consulta la documentación del SDK para conocer los datos de entrada requeridos y su semántica. - Haz que sea seguro repetir los efectos secundarios. Para las acciones ajenas al estado de la propia sesión del agente, usa claves de idempotencia a nivel de aplicación, deduplicación o una etapa de aprobación humana cuando corresponda.
Evita envolver start en un bucle de reintentos incondicional. Si la solicitud inicial pudo haber creado una sesión antes de que quien la llamó perdiera la respuesta, otro start puede generar un trabajo independiente. La referencia de la API no documenta una clave de idempotencia para start, así que no des por hecho que existe.
Soluciona fallos habituales en producción
La sesión se inicia con un entorno de ejecución incorrecto
Registra el modo de backend seleccionado y los identificadores de sesión que no sean secretos. Comprueba las opciones backendMode, hub y remote en relación con el entorno donde se ejecuta el proceso de trabajo. La referencia las describe como opciones de selección del entorno de ejecución, pero no documenta el comportamiento de conmutación por error automática. Verifica qué hace auto en la versión de tu SDK, en lugar de confiar en una alternativa supuesta.
Las herramientas no están disponibles o se permiten de forma inesperada
Comprueba tanto el config de la sesión como las toolPolicies o capabilities predeterminadas y específicas de la sesión que correspondan. La referencia las identifica como controles de política de herramientas y de ejecutores o aprobaciones gestionados por el cliente. El resumen de la API proporcionado no detalla la precedencia de las políticas, así que confírmala en la documentación del SDK instalado y prueba tanto los casos permitidos como los denegados.
Un proceso de trabajo pierde la conexión durante la ejecución
Conserva el ID de sesión y el ID del trabajo en un estado persistente de la aplicación. Al reiniciar, inspecciona la sesión existente antes de decidir si continuar con send, detenerla o restaurarla desde un punto de control. No deduzcas que el trabajo se completó solo porque no llegó una respuesta.
Falla la configuración del proveedor o del modelo
Verifica el ID del proveedor, el ID del modelo, las credenciales y los requisitos del endpoint con la documentación del proveedor y de Cline para la configuración que hayas elegido. La referencia de ClineCore muestra una estructura de configuración para proveedor y modelo, pero no garantiza que endpoints arbitrarios compatibles con OpenAI o parámetros específicos de un proveedor vayan a funcionar sin cambios.
Lista de comprobación para producción
- Almacena los ID de sesión de forma persistente y mantén los secretos fuera de los registros y metadatos.
- Define los permisos de las herramientas de forma explícita y prueba las rutas de aprobación y denegación.
- Distingue entre una operación fallida y una operación cuyo resultado se desconoce.
- Inspecciona el historial de la sesión antes de volver a enviar el trabajo.
- Haz que los efectos secundarios externos sean idempotentes o exige aprobación antes de repetirlos.
- Valida el comportamiento del backend y del proveedor en el entorno real de despliegue.
- Libera los recursos del entorno de ejecución durante un apagado ordenado, siguiendo el ciclo de vida documentado del SDK.
La regla práctica es sencilla: reintenta solo cuando sepas qué estás reintentando. ClineCore ofrece API relacionadas con sesiones y recuperación, pero un comportamiento seguro en producción sigue dependiendo del seguimiento persistente de trabajos, el diseño de permisos y la gestión de efectos secundarios duplicados en tu aplicación.
FAQ
¿Qué ajustes de ClineCore son independientes del proveedor del modelo?
Las opciones del entorno de ejecución, como `clientName`, `backendMode`, los ajustes opcionales de hub o conexión remota, las capacidades, las políticas de herramientas y la automatización, son independientes de los campos de proveedor y modelo de la sesión. Consulta la versión del SDK que uses para conocer el comportamiento exacto de cada opción.
¿Debería reintentar ClineCore.start después de que se agote el tiempo de espera?
No lo hagas a ciegas. Un tiempo de espera agotado no indica si se creó una sesión. Persiste el ID de sesión cuando esté disponible e inspecciona las sesiones existentes antes de iniciar trabajo nuevo. La referencia de la API proporcionada no documenta una clave de idempotencia para `start`.
¿Puede ClineCore restaurar una sesión fallida?
La referencia de la API enumera un método `restore`, pero el resumen proporcionado no especifica los datos de entrada requeridos ni la semántica de los puntos de control. Consulta la documentación del SDK instalado antes de basar tu estrategia de recuperación en este método.
¿Funciona esta configuración con cualquier proveedor compatible con OpenAI?
La referencia de ClineCore citada no lo establece. La compatibilidad del proveedor y los parámetros aceptados dependen de la compatibilidad documentada con el endpoint y de la configuración del proveedor seleccionado. Verifícalos en vez de dar por hecho que son intercambiables.
Artículos relacionados
Guides
Cómo configurar Cline para evaluaciones reproducibles de agentes de programación
Configura sesiones de ClineCore con entradas fijas, límites explícitos para las herramientas, casos de prueba reproducibles y una lista de comprobación para solucionar problemas.
Guides
Configura Cline para diagnosticar un incidente de API
Configura una sesión del SDK de Cline para diagnosticar un incidente de API, elige ajustes de ejecución independientes del proveedor y resuelve señales de fallo observables.
Guides
Evalúa modelos de Hugging Face para tomar decisiones fiables de reintento y recuperación
Diseña una evaluación reproducible y específica de la tarea para comparar modelos de Hugging Face en decisiones de reintento y recuperación en producción.
Guides
Configura ClineCore para sesiones de programación con privacidad
Guía práctica para configurar sesiones de ClineCore, limitar la exposición de datos sensibles y resolver problemas habituales de configuración.