Servicios de modelos locales

models.providers.<id>.localService permite que OmeniaClaw inicie bajo demanda un servidor de modelos local propiedad del proveedor. Es configuración a nivel de proveedor: cuando el modelo seleccionado pertenece a ese proveedor, OmeniaClaw sondea el servicio, inicia el proceso si el endpoint está inactivo, espera a que esté listo y luego envía la solicitud del modelo.

Úsalo para servidores locales que sean costosos de mantener ejecutándose todo el día, o para configuraciones manuales donde la selección del modelo debería bastar para levantar el backend.

Cómo funciona

1. Una solicitud de modelo se resuelve en un proveedor configurado.
2. Si ese proveedor tiene localService, OmeniaClaw sondea healthUrl.
3. Si el sondeo se realiza correctamente, OmeniaClaw usa el servidor existente.
4. Si el sondeo falla, OmeniaClaw inicia command con args.
5. OmeniaClaw sondea la disponibilidad hasta que vence readyTimeoutMs.
6. La solicitud del modelo se envía a través del transporte normal del proveedor.
7. Si OmeniaClaw inició el proceso y idleStopMs es positivo, el proceso se detiene después de que la última solicitud en curso haya estado inactiva durante ese tiempo.

OmeniaClaw no instala launchd, systemd, Docker ni un daemon para esto. El servidor es un proceso hijo del proceso de OmeniaClaw que lo necesitó primero.

Estructura de configuración

{  models: {    providers: {      local: {        baseUrl: "http://127.0.0.1:8000/v1",        apiKey: "local-model",        api: "openai-completions",        timeoutSeconds: 300,        localService: {          command: "/absolute/path/to/server",          args: ["--host", "127.0.0.1", "--port", "8000"],          cwd: "/absolute/path/to/working-dir",          env: { LOCAL_MODEL_CACHE: "/absolute/path/to/cache" },          healthUrl: "http://127.0.0.1:8000/v1/models",          readyTimeoutMs: 180000,          idleStopMs: 0,        },        models: [          {            id: "my-local-model",            name: "My Local Model",            reasoning: false,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 131072,            maxTokens: 8192,          },        ],      },    },  },}

Campos

• command: ruta absoluta del ejecutable. No se usa la búsqueda del shell.
• args: argumentos del proceso. No se aplican expansión del shell, tuberías, globbing ni reglas de entrecomillado.
• cwd: directorio de trabajo opcional para el proceso.
• env: variables de entorno opcionales combinadas sobre el entorno del proceso de OmeniaClaw.
• healthUrl: URL de disponibilidad. Si se omite, OmeniaClaw añade /models a baseUrl, por lo que http://127.0.0.1:8000/v1 pasa a ser http://127.0.0.1:8000/v1/models.
• readyTimeoutMs: plazo límite de disponibilidad al iniciar. Predeterminado: 120000.
• idleStopMs: retardo de apagado por inactividad para procesos iniciados por OmeniaClaw. 0 u omitido mantiene el proceso activo hasta que OmeniaClaw salga.

Ejemplo de Inferrs

Inferrs es un backend /v1 personalizado compatible con OpenAI, por lo que la misma API de servicio local funciona con la entrada del proveedor inferrs.

{  agents: {    defaults: {      model: { primary: "inferrs/google/gemma-4-E2B-it" },    },  },  models: {    mode: "merge",    providers: {      inferrs: {        baseUrl: "http://127.0.0.1:8080/v1",        apiKey: "inferrs-local",        api: "openai-completions",        timeoutSeconds: 300,        localService: {          command: "/opt/homebrew/bin/inferrs",          args: [            "serve",            "google/gemma-4-E2B-it",            "--host",            "127.0.0.1",            "--port",            "8080",            "--device",            "metal",          ],          healthUrl: "http://127.0.0.1:8080/v1/models",          readyTimeoutMs: 180000,          idleStopMs: 0,        },        models: [          {            id: "google/gemma-4-E2B-it",            name: "Gemma 4 E2B (inferrs)",            reasoning: false,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 131072,            maxTokens: 4096,            compat: {              requiresStringContent: true,            },          },        ],      },    },  },}

Sustituye command por el resultado de which inferrs en la máquina que ejecuta OmeniaClaw.

Ejemplo de ds4

{  models: {    providers: {      ds4: {        baseUrl: "http://127.0.0.1:18000/v1",        apiKey: "ds4-local",        api: "openai-completions",        timeoutSeconds: 300,        localService: {          command: "/Users/you/Projects/oss/ds4/ds4-server",          args: [            "--model",            "/Users/you/Projects/oss/ds4/ds4flash.gguf",            "--host",            "127.0.0.1",            "--port",            "18000",            "--ctx",            "393216",          ],          cwd: "/Users/you/Projects/oss/ds4",          healthUrl: "http://127.0.0.1:18000/v1/models",          readyTimeoutMs: 300000,          idleStopMs: 0,        },        models: [],      },    },  },}

Notas operativas

• Un proceso de OmeniaClaw administra el hijo que inició. Otro proceso de OmeniaClaw que vea que la misma URL de estado ya está activa la reutilizará sin adoptarla.
• El inicio se serializa por comando de proveedor y conjunto de argumentos, por lo que las solicitudes concurrentes no generan servidores duplicados para la misma configuración.
• Las respuestas de streaming activas mantienen una concesión; el apagado por inactividad espera hasta que se complete el manejo del cuerpo de la respuesta.
• Usa timeoutSeconds en proveedores locales lentos para que los arranques en frío y las generaciones largas no alcancen el tiempo de espera predeterminado de solicitud de modelo.
• Usa un healthUrl explícito si tu servidor expone la disponibilidad en un lugar distinto de /v1/models.

Relacionado