Ir al contenido
OpenClaw Docs

Ollama

OpenClaw se integra con la API nativa de Ollama (/api/chat) para modelos en la nube alojados y servidores Ollama locales/autoalojados. Puede usar Ollama en tres modos: Cloud + Local a través de un host Ollama accesible, Cloud only contra https://ollama.com, o Local only contra un host Ollama accesible.

OpenClaw también registra ollama-cloud como un id de proveedor alojado de primera clase para el uso directo de Ollama Cloud. Use referencias como ollama-cloud/kimi-k2.5:cloud cuando quiera un enrutamiento solo en la nube sin compartir el id del proveedor local ollama.

Para la página de configuración dedicada solo para la nube, consulte Ollama Cloud.

La configuración del proveedor Ollama usa baseUrl como clave canónica. OpenClaw también acepta baseURL para compatibilidad con ejemplos de estilo OpenAI SDK, pero la nueva configuración debería preferir baseUrl.

Reglas de autenticación

Sección titulada «Reglas de autenticación»
Hosts locales y de LAN

Los hosts Ollama locales y de LAN no necesitan un token de portador real. OpenClaw usa el marcador local ollama-local solo para bucle invertido, red privada, .local y URL base de Ollama de nombre de host simple.

Hosts remotos y Ollama Cloud

Los hosts públicos remotos y Ollama Cloud (https://ollama.com) requieren una credencial real a través de OLLAMA_API_KEY, un perfil de autenticación o el apiKey del proveedor. Para uso alojado directo, prefiera el proveedor ollama-cloud.

Ids de proveedor personalizados

Los ids de proveedor personalizados que establecen api: "ollama" siguen las mismas reglas. Por ejemplo, un proveedor ollama-remote que apunta a un host Ollama de LAN privada puede usar apiKey: "ollama-local" y los sub-agentes resolverán ese marcador a través del enlace del proveedor Ollama en lugar de tratarlo como una credencial faltante. La búsqueda de memoria también puede establecer agents.defaults.memorySearch.provider en ese id de proveedor personalizado para que los incrustamientos usen el punto final Ollama coincidente.

Perfiles de autenticación

auth-profiles.json almacena la credencial para un id de proveedor. Coloque la configuración del punto final (baseUrl, api, ids de modelo, encabezados, tiempos de espera) en `models.providers.

. Los archivos de perfil de autenticación planos antiguos como { “ollama-windows”: { “apiKey”: “ollama-local” } }no son un formato de tiempo de ejecución; ejecuteopenclaw doctor —fixpara reescribirlos al perfil de clave de APIollama-windows:defaultcanónico con una copia de seguridad.baseUrl` en ese archivo es ruido de compatibilidad y debe moverse a la configuración del proveedor.

Ámbito de incrustación de memoria

Cuando Ollama se usa para incrustaciones de memoria, la autenticación de portador está limitada al host donde se declaró:

  • Una clave de nivel de proveedor se envía solo al host Ollama de ese proveedor.
  • agents.*.memorySearch.remote.apiKey se envía solo a su host de incrustación remoto.
  • Un valor de entorno OLLAMA_API_KEY puro se trata como la convención de Ollama Cloud, no se envía a hosts locales o autoalojados de forma predeterminada.

Para comenzar

Sección titulada «Para comenzar»

Elija su método de configuración y modo preferidos.

Lo mejor para: la ruta más rápida para una configuración funcional de Ollama en la nube o local.

  1. Ejecutar incorporación

    Ventana de terminal
    openclaw onboard

    Seleccione Ollama de la lista de proveedores.

  2. Elija su modo

    • Nube + Local — host local de Ollama más modelos en la nube enrutados a través de ese host
    • Solo nube — modelos de Ollama alojados a través de https://ollama.com
    • Solo local — solo modelos locales

  3. Seleccione un modelo

    Cloud only solicita OLLAMA_API_KEY y sugiere valores predeterminados en la nube alojados. Cloud + Local y Local only piden una URL base de Ollama, descubren los modelos disponibles y extraen automáticamente el modelo local seleccionado si aún no está disponible. Cuando Ollama informa una etiqueta :latest instalada como gemma4:latest, la configuración muestra ese modelo instalado una vez en lugar de mostrar tanto gemma4 como gemma4:latest o volver a extraer el alias básico. Cloud + Local también verifica si ese host de Ollama ha iniciado sesión para el acceso a la nube.

  4. Verificar que el modelo esté disponible

    Ventana de terminal
    openclaw models list --provider ollama

Modo no interactivo

Sección titulada «Modo no interactivo»
Ventana de terminal
openclaw onboard --non-interactive \
  --auth-choice ollama \
  --accept-risk

Opcionalmente especifique una URL base o modelo personalizado:

Ventana de terminal
openclaw onboard --non-interactive \
  --auth-choice ollama \
  --custom-base-url "http://ollama-host:11434" \
  --custom-model-id "qwen3.5:27b" \
  --accept-risk

Modelos en la nube

Sección titulada «Modelos en la nube»

Cloud + Local utiliza un host Ollama accesible como punto de control tanto para modelos locales como en la nube. Este es el flujo híbrido preferido de Ollama.

Usa Nube + Local durante la configuración. OpenClaw solicita la URL base de Ollama, descubre modelos locales de ese host y verifica si el host ha iniciado sesión para el acceso en la nube con ollama signin. Cuando el host ha iniciado sesión, OpenClaw también sugiere valores predeterminados en la nube alojados, como kimi-k2.5:cloud, minimax-m2.7:cloud y glm-5.1:cloud.

Si el host aún no ha iniciado sesión, OpenClaw mantiene la configuración solo local hasta que ejecutes ollama signin.

Descubrimiento de modelos (proveedor implícito)

Sección titulada «Descubrimiento de modelos (proveedor implícito)»

Cuando configura OLLAMA_API_KEY (o un perfil de autenticación) y no define models.providers.ollama u otro proveedor remoto personalizado con api: "ollama", OpenClaw descubre modelos desde la instancia local de Ollama en http://127.0.0.1:11434.

ComportamientoDetalle
Consulta de catálogoConsultas /api/tags
Detección de capacidadesUtiliza búsquedas de /api/show de mejor esfuerzo para leer contextWindow, parámetros expandidos de Modelfile num_ctx y capacidades que incluyen visión/herramientas
Modelos de visiónLos modelos con una capacidad vision reportada por /api/show se marcan como compatibles con imágenes (input: ["text", "image"]), por lo que OpenClaw inyecta automáticamente imágenes en el indicador
Detección de razonamientoUsa las capacidades de /api/show cuando están disponibles, incluyendo thinking; recurre a un heurístico de nombre de modelo (r1, reasoning, think) cuando Ollama omite capacidades
Límites de tokensEstablece maxTokens al límite máximo de tokens predeterminado de Ollama utilizado por OpenClaw
CostosEstablece todos los costos en 0

Esto evita entradas de modelo manuales manteniendo el catálogo alineado con la instancia local de Ollama. Puede usar una referencia completa como ollama/<pulled-model>:latest en infer model run local; OpenClaw resuelve ese modelo instalado desde el catálogo en vivo de Ollama sin requerir una entrada models.json escrita manualmente.

Para hosts de Ollama con sesión iniciada, algunos modelos :cloud pueden ser utilizables a través de /api/chat y /api/show antes de que aparezcan en /api/tags. Cuando selecciona explícitamente una referencia completa de ollama/<model>:cloud, OpenClaw valida ese modelo faltante exacto con /api/show y lo agrega al catálogo de tiempo de ejecución solo si Ollama confirma los metadatos del modelo. Los errores tipográficos aún fallarán como modelos desconocidos en lugar de ser autocreados.

Ventana de terminal
# See what models are available
ollama list
openclaw models list

Para una prueba de humo de generación de texto reducida que evite la superficie completa de herramientas de agente, use infer model run local con una referencia completa de modelo de Ollama:

Ventana de terminal
OLLAMA_API_KEY=ollama-local \
  openclaw infer model run \
    --local \
    --model ollama/llama3.2:latest \
    --prompt "Reply with exactly: pong" \
    --json

Esa ruta todavía usa el proveedor configurado, la autenticación y el transporte nativo de Ollama de OpenClaw, pero no inicia un turno de agente de chat ni carga el contexto de MCP/herramientas. Si esto tiene éxito mientras que las respuestas normales del agente fallan, solucione los problemas de la capacidad de prompt/herramienta del agente del modelo a continuación.

Para una prueba de humo de modelo de visión reducida en la misma ruta simplificada, agregue uno o más archivos de imagen a infer model run. Esto envía el prompt y la imagen directamente al modelo de visión de Ollama seleccionado sin cargar herramientas de chat, memoria o contexto de sesión previa:

Ventana de terminal
OLLAMA_API_KEY=ollama-local \
  openclaw infer model run \
    --local \
    --model ollama/qwen2.5vl:7b \
    --prompt "Describe this image in one sentence." \
    --file ./photo.jpg \
    --json

model run --file acepta archivos detectados como image/*, incluyendo entradas comunes de PNG, JPEG y WebP. Los archivos que no son imágenes se rechazan antes de llamar a Ollama. Para el reconocimiento de voz, use openclaw infer audio transcribe en su lugar.

Cuando cambias una conversación con /model ollama/<model>, OpenClaw lo trata como una selección exacta del usuario. Si el proveedor de Ollama baseUrl configurado es inalcanzable, la siguiente respuesta fallará con el error del proveedor en lugar de responder silenciosamente desde otro modelo alternativo configurado.

Los trabajos cron aislados realizan una verificación de seguridad local adicional antes de iniciar el turno del agente. Si el modelo seleccionado se resuelve en un proveedor de Ollama local, de red privada o .local y /api/tags es inalcanzable, OpenClaw registra esa ejecución cron como skipped con el ollama/<model> seleccionado en el texto de error. La comprobación previa del punto final se almacena en caché durante 5 minutos, por lo que múltiples trabajos cron dirigidos al mismo demonio de Ollama detenido no lanzan todas las solicitudes de modelo fallidas.

Verifique en vivo la ruta de texto local, la ruta de transmisión nativa y los incrustamientos con Ollama local usando:

Ventana de terminal
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA=1 OPENCLAW_LIVE_OLLAMA_WEB_SEARCH=0 \
  pnpm test:live -- extensions/ollama/ollama.live.test.ts

Para pruebas de humo de la clave API de Ollama Cloud, apunte la prueba en vivo a https://ollama.com y elija un modelo alojado del catálogo actual:

Ventana de terminal
export OLLAMA_API_KEY='<your-ollama-cloud-api-key>'


OPENCLAW_LIVE_TEST=1 \
OPENCLAW_LIVE_OLLAMA=1 \
OPENCLAW_LIVE_OLLAMA_BASE_URL=https://ollama.com \
OPENCLAW_LIVE_OLLAMA_MODEL=glm-5.1:cloud \
OPENCLAW_LIVE_OLLAMA_WEB_SEARCH=1 \
pnpm test:live -- extensions/ollama/ollama.live.test.ts

La prueba de humo en la nube ejecuta texto, transmisión nativa y búsqueda web. Omite los incrustamientos de forma predeterminada para https://ollama.com porque las claves API de Ollama Cloud pueden no autorizar /api/embed. Establezca OPENCLAW_LIVE_OLLAMA_EMBEDDINGS=1 cuando desee explícitamente que la prueba en vivo falle si la clave de nube configurada no puede usar el punto final de incrustamiento.

Para agregar un nuevo modelo, simplemente extráigalo con Ollama:

Ventana de terminal
ollama pull mistral

El nuevo modelo se descubrirá automáticamente y estará disponible para su uso.

Visión y descripción de imágenes

Sección titulada «Visión y descripción de imágenes»

El complemento Ollama incluido registra a Ollama como un proveedor de comprensión de medios con capacidad de imagen. Esto permite que OpenClaw enrute solicitudes explícitas de descripción de imágenes y valores predeterminados de modelo de imagen configurados a través de modelos de visión de Ollama locales o alojados.

Para visión local, extraiga un modelo que admita imágenes:

Ventana de terminal
ollama pull qwen2.5vl:7b
export OLLAMA_API_KEY="ollama-local"

Luego verifique con la CLI de inferencia:

Ventana de terminal
openclaw infer image describe \
  --file ./photo.jpg \
  --model ollama/qwen2.5vl:7b \
  --json

--model debe ser una referencia completa de <provider/model>. Cuando se establece, openclaw infer image describe ejecuta ese modelo directamente en lugar de omitir la descripción porque el modelo admite visión nativa.

Use infer image describe cuando quiera el flujo del proveedor de comprensión de imágenes de OpenClaw, configurado agents.defaults.imageModel y la forma de salida de descripción de imágenes. Use infer model run --file cuando quiera una sonda de modelo multimodal sin procesar con un mensaje personalizado y una o más imágenes.

Para hacer que Ollama sea el modelo de comprensión de imágenes predeterminado para los medios entrantes, configure agents.defaults.imageModel:

{
  agents: {
    defaults: {
      imageModel: {
        primary: "ollama/qwen2.5vl:7b",
      },
    },
  },
}

Prefiera la referencia completa de ollama/<model>. Si el mismo modelo aparece en models.providers.ollama.models con input: ["text", "image"] y ningún otro proveedor de imágenes configurado expone ese ID de modelo simple, OpenClaw también normaliza una referencia simple de imageModel como qwen2.5vl:7b a ollama/qwen2.5vl:7b. Si más de un proveedor de imágenes configurado tiene el mismo ID simple, use explícitamente el prefijo del proveedor.

Los modelos de visión locales lentos pueden necesitar un tiempo de espera de comprensión de imágenes más largo que los modelos en la nube. También pueden bloquearse o detenerse cuando Ollama intenta asignar el contexto de visión completo anunciado en hardware con restricciones. Establezca un tiempo de espera de capacidad y limite num_ctx en la entrada del modelo cuando solo necesite un turno de descripción de imagen normal:

{
  models: {
    providers: {
      ollama: {
        models: [
          {
            id: "qwen2.5vl:7b",
            name: "qwen2.5vl:7b",
            input: ["text", "image"],
            params: { num_ctx: 2048, keep_alive: "1m" },
          },
        ],
      },
    },
  },
  tools: {
    media: {
      image: {
        timeoutSeconds: 180,
        models: [{ provider: "ollama", model: "qwen2.5vl:7b", timeoutSeconds: 300 }],
      },
    },
  },
}

Este tiempo de espera se aplica a la comprensión de imágenes entrantes y a la herramienta explícita image que el agente puede llamar durante un turno. El models.providers.ollama.timeoutSeconds a nivel de proveedor todavía controla el guardia de solicitud HTTP de Ollama subyacente para llamadas de modelo normales.

Verifique en vivo la herramienta de imagen explícita contra Ollama local con:

Ventana de terminal
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \
  pnpm test:live -- src/agents/tools/image-tool.ollama.live.test.ts

Si define models.providers.ollama.models manualmente, marque los modelos de visión con soporte de entrada de imagen:

{
  id: "qwen2.5vl:7b",
  name: "qwen2.5vl:7b",
  input: ["text", "image"],
  contextWindow: 128000,
  maxTokens: 8192,
}

OpenClaw rechaza las solicitudes de descripción de imágenes para modelos que no están marcados como capaces de imagen. Con el descubrimiento implícito, OpenClaw lee esto de Ollama cuando /api/show informa una capacidad de visión.

Configuración

Sección titulada «Configuración»

La ruta de habilitación más sencilla solo local es a través de una variable de entorno:

Ventana de terminal
export OLLAMA_API_KEY="ollama-local"

Recetas comunes

Sección titulada «Recetas comunes»

Úselos como puntos de partida y reemplace los ID de los modelos con los nombres exactos de ollama list o openclaw models list --provider ollama.

Modelo local con descubrimiento automático

Use esto cuando Ollama se ejecuta en la misma máquina que la Gateway y desea que OpenClaw descubra los modelos instalados automáticamente.

Ventana de terminal
ollama serve
ollama pull gemma4
export OLLAMA_API_KEY="ollama-local"
openclaw models list --provider ollama
openclaw models set ollama/gemma4

Esta ruta mantiene la configuración al mínimo. No agregue un bloque models.providers.ollama a menos que desee definir modelos manualmente.

Host Ollama en LAN con modelos manuales

Use las URL nativas de Ollama para hosts LAN. No agregue /v1.

{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://gpu-box.local:11434",
        apiKey: "ollama-local",
        api: "ollama",
        timeoutSeconds: 300,
        contextWindow: 32768,
        maxTokens: 8192,
        models: [
          {
            id: "qwen3.5:9b",
            name: "qwen3.5:9b",
            reasoning: true,
            input: ["text"],
            params: {
              num_ctx: 32768,
              thinking: false,
              keep_alive: "15m",
            },
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "ollama/qwen3.5:9b" },
    },
  },
}

contextWindow es el presupuesto de contexto del lado de OpenClaw. params.num_ctx se envía a Ollama para la solicitud. Manténgalos alineados cuando su hardware no pueda ejecutar el contexto completo anunciado del modelo.

Solo Ollama Cloud

Use esto cuando no ejecute un demonio local y desee modelos de Ollama alojados directamente.

Ventana de terminal
export OLLAMA_API_KEY="your-ollama-api-key"
{
  models: {
    providers: {
      ollama: {
        baseUrl: "https://ollama.com",
        apiKey: "OLLAMA_API_KEY",
        api: "ollama",
        models: [
          {
            id: "kimi-k2.5:cloud",
            name: "kimi-k2.5:cloud",
            reasoning: false,
            input: ["text", "image"],
            contextWindow: 128000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "ollama/kimi-k2.5:cloud" },
    },
  },
}
Nube más local a través de un demonio con sesión iniciada

Use esto cuando un demonio local o de LAN de Ollama haya iniciado sesión con ollama signin y deba servir tanto modelos locales como modelos :cloud.

Ventana de terminal
ollama signin
ollama pull gemma4
{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://127.0.0.1:11434",
        apiKey: "ollama-local",
        api: "ollama",
        timeoutSeconds: 300,
        models: [
          { id: "gemma4", name: "gemma4", input: ["text"] },
          { id: "kimi-k2.5:cloud", name: "kimi-k2.5:cloud", input: ["text", "image"] },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: "ollama/gemma4",
        fallbacks: ["ollama/kimi-k2.5:cloud"],
      },
    },
  },
}
Múltiples hosts de Ollama

Utilice IDs de proveedor personalizados cuando tenga más de un servidor Ollama. Cada proveedor obtiene su propio host, modelos, autenticación, tiempo de espera y referencias de modelos.

{
  models: {
    providers: {
      "ollama-fast": {
        baseUrl: "http://mini.local:11434",
        apiKey: "ollama-local",
        api: "ollama",
        contextWindow: 32768,
        models: [{ id: "gemma4", name: "gemma4", input: ["text"] }],
      },
      "ollama-large": {
        baseUrl: "http://gpu-box.local:11434",
        apiKey: "ollama-local",
        api: "ollama",
        timeoutSeconds: 420,
        contextWindow: 131072,
        maxTokens: 16384,
        models: [{ id: "qwen3.5:27b", name: "qwen3.5:27b", input: ["text"] }],
      },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: "ollama-fast/gemma4",
        fallbacks: ["ollama-large/qwen3.5:27b"],
      },
    },
  },
}

Cuando OpenClaw envía la solicitud, se elimina el prefijo del proveedor activo, de modo que ollama-large/qwen3.5:27b llega a Ollama como qwen3.5:27b.

Perfil de modelo local ligero

Algunos modelos locales pueden responder indicaciones simples pero luchan con la superficie completa de herramientas del agente. Comience limitando las herramientas y el contexto antes de cambiar la configuración global de tiempo de ejecución.

{
  agents: {
    list: [
      {
        id: "local",
        experimental: {
          localModelLean: true,
        },
        model: { primary: "ollama/gemma4" },
      },
    ],
  },
  models: {
    providers: {
      ollama: {
        baseUrl: "http://127.0.0.1:11434",
        apiKey: "ollama-local",
        api: "ollama",
        contextWindow: 32768,
        models: [
          {
            id: "gemma4",
            name: "gemma4",
            input: ["text"],
            params: { num_ctx: 32768 },
            compat: { supportsTools: false },
          },
        ],
      },
    },
  },
}

Use compat.supportsTools: false solo cuando el modelo o el servidor fallan de manera confiable en los esquemas de herramientas. Intercambia la capacidad del agente por estabilidad. localModelLean elimina las herramientas del navegador, cron y mensajes de la superficie del agente, pero no cambia el contexto de tiempo de ejecución ni el modo de pensamiento de Ollama. Combínelo con params.num_ctx y params.thinking: false explícitos para modelos pequeños de pensamiento estilo Qwen que entran en bucle o gastan su presupuesto de respuesta en razonamiento oculto.

Selección de modelo

Sección titulada «Selección de modelo»

Una vez configurados, todos sus modelos de Ollama están disponibles:

{
  agents: {
    defaults: {
      model: {
        primary: "ollama/gpt-oss:20b",
        fallbacks: ["ollama/llama3.3", "ollama/qwen2.5-coder:32b"],
      },
    },
  },
}

También se admiten IDs de proveedor de Ollama personalizados. Cuando una referencia de modelo utiliza el prefijo del proveedor activo, como ollama-spark/qwen3:32b, OpenClaw elimina solo ese prefijo antes de llamar a Ollama, de modo que el servidor recibe qwen3:32b.

Para modelos locales lentos, prefiera el ajuste de solicitudes con ámbito de proveedor antes de aumentar todo el tiempo de espera de ejecución del agente:

{
  models: {
    providers: {
      ollama: {
        timeoutSeconds: 300,
        models: [
          {
            id: "gemma4:26b",
            name: "gemma4:26b",
            params: { keep_alive: "15m" },
          },
        ],
      },
    },
  },
}

timeoutSeconds se aplica a la solicitud HTTP del modelo, incluyendo la configuración de la conexión, encabezados, transmisión del cuerpo y la interrupción total de la recuperación protegida. params.keep_alive se reenvía a Ollama como keep_alive de nivel superior en las solicitudes nativas /api/chat; establézcalo por modelo cuando el tiempo de carga del primer turno sea el cuello de botella.

Verificación rápida

Sección titulada «Verificación rápida»
Ventana de terminal
# Ollama daemon visible to this machine
curl http://127.0.0.1:11434/api/tags


# OpenClaw catalog and selected model
openclaw models list --provider ollama
openclaw models status


# Direct model smoke
openclaw infer model run \
  --model ollama/gemma4 \
  --prompt "Reply with exactly: ok"

Para hosts remotos, reemplace 127.0.0.1 con el host utilizado en baseUrl. Si curl funciona pero OpenClaw no, verifique si el Gateway se ejecuta en una máquina, contenedor o cuenta de servicio diferente.

Búsqueda web de Ollama

Sección titulada «Búsqueda web de Ollama»

OpenClaw admite Búsqueda web de Ollama como proveedor web_search incluido.

PropiedadDetalle
HostUtiliza su host de Ollama configurado (models.providers.ollama.baseUrl si está configurado, de lo contrario http://127.0.0.1:11434); https://ollama.com utiliza la API alojada directamente
AutenticaciónSin clave para hosts locales de Ollama con sesión iniciada; OLLAMA_API_KEY o autenticación de proveedor configurada para búsqueda directa https://ollama.com o hosts protegidos por autenticación
RequisitoLos hosts locales/autoalojados deben estar ejecutándose y con sesión iniciada con ollama signin; la búsqueda alojada directa requiere baseUrl: "https://ollama.com" más una clave de API real de Ollama

Elija Búsqueda web de Ollama durante openclaw onboard o openclaw configure --section web, o configure:

{
  tools: {
    web: {
      search: {
        provider: "ollama",
      },
    },
  },
}

Para búsqueda alojada directa a través de Ollama Cloud:

{
  models: {
    providers: {
      ollama: {
        baseUrl: "https://ollama.com",
        apiKey: "OLLAMA_API_KEY",
        api: "ollama",
        models: [{ id: "kimi-k2.5:cloud", name: "kimi-k2.5:cloud", input: ["text"] }],
      },
    },
  },
  tools: {
    web: {
      search: { provider: "ollama" },
    },
  },
}

Para un demonio local con sesión iniciada, OpenClaw utiliza el proxy /api/experimental/web_search del demonio. Para https://ollama.com, llama directamente al endpoint /api/web_search alojado.

Configuración avanzada

Sección titulada «Configuración avanzada»
Modo compatible con OpenAI heredado

Si necesita usar el endpoint compatible con OpenAI en su lugar (por ejemplo, detrás de un proxy que solo admite el formato OpenAI), establezca api: "openai-completions" explícitamente:

{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://ollama-host:11434/v1",
        api: "openai-completions",
        injectNumCtxForOpenAICompat: true, // default: true
        apiKey: "ollama-local",
        models: [...]
      }
    }
  }
}

Este modo puede no admitir streaming y llamada a herramientas simultáneamente. Es posible que necesite deshabilitar el streaming con params: { streaming: false } en la configuración del modelo.

Cuando se usa api: "openai-completions" con Ollama, OpenClaw inyecta options.num_ctx de manera predeterminada para que Ollama no regrese silenciosamente a una ventana de contexto de 4096. Si su proxy/upstream rechaza campos options desconocidos, deshabilite este comportamiento:

{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://ollama-host:11434/v1",
        api: "openai-completions",
        injectNumCtxForOpenAICompat: false,
        apiKey: "ollama-local",
        models: [...]
      }
    }
  }
}
Ventanas de contexto

Para los modelos descubiertos automáticamente, OpenClaw utiliza la ventana de contexto reportada por Ollama cuando está disponible, incluidos los valores más grandes de PARAMETER num_ctx de los Modelfiles personalizados. De lo contrario, recurre a la ventana de contexto predeterminada de Ollama utilizada por OpenClaw.

Puede establecer los valores predeterminados a nivel de proveedor para contextWindow, contextTokens y maxTokens para cada modelo bajo ese proveedor de Ollama, y luego anularlos por modelo según sea necesario. contextWindow es el presupuesto de prompt y compactación de OpenClaw. Las solicitudes nativas de Ollama dejan options.num_ctx sin establecer a menos que configure explícitamente params.num_ctx, por lo que Ollama puede aplicar su propio modelo, OLLAMA_CONTEXT_LENGTH o valor predeterminado basado en VRAM. Para limitar o forzar el contexto de tiempo de ejecución por solicitud de Ollama sin reconstruir un Modelfile, configure params.num_ctx; se ignoran los valores no válidos, cero, negativos y no finitos. Si actualizó una configuración anterior que usaba solo contextWindow o maxTokens para forzar un contexto de solicitud nativa de Ollama, ejecute openclaw doctor --fix para copiar esos presupuestos explícitos de proveedor o modelo en params.num_ctx. El adaptador compatible con OpenAI de Ollama aún inyecta options.num_ctx de manera predeterminada desde el params.num_ctx configurado o el contextWindow; desactívelo con injectNumCtxForOpenAICompat: false si su servicio ascendente rechaza options.

Las entradas de modelos nativos de Ollama también aceptan las opciones comunes de tiempo de ejecución de Ollama bajo params, incluidas temperature, top_p, top_k, min_p, num_predict, stop, repeat_penalty, num_batch, num_thread y use_mmap. OpenClaw reenvía solo las claves de solicitud de Ollama, por lo que los parámetros de tiempo de ejecución de OpenClaw como streaming no se filtran a Ollama. Use params.think o params.thinking para enviar think de nivel superior de Ollama; false desactiva el pensamiento a nivel de API para los modelos de pensamiento estilo Qwen.

{
  models: {
    providers: {
      ollama: {
        contextWindow: 32768,
        models: [
          {
            id: "llama3.3",
            contextWindow: 131072,
            maxTokens: 65536,
            params: {
              num_ctx: 32768,
              temperature: 0.7,
              top_p: 0.9,
              thinking: false,
            },
          }
        ]
      }
    }
  }
}

El `agents.defaults.models[“ollama/

“].params.num_ctx` por modelo también funciona. Si ambos están configurados, la entrada del modelo de proveedor explícito tiene prioridad sobre el valor predeterminado del agente.

Control del pensamiento

Para los modelos nativos de Ollama, OpenClaw reenvía el control del pensamiento como Ollama espera: think de nivel superior, no options.think. Los modelos descubiertos automáticamente cuya respuesta /api/show incluye la capacidad thinking exponen /think low, /think medium, /think high y /think max; los modelos no pensantes exponen solo /think off.

Ventana de terminal
openclaw agent --model ollama/gemma4 --thinking off
openclaw agent --model ollama/gemma4 --thinking low

También puedes establecer un valor predeterminado del modelo:

{
  agents: {
    defaults: {
      models: {
        "ollama/gemma4": {
          thinking: "low",
        },
      },
    },
  },
}

El params.think o params.thinking por modelo puede desactivar o forzar el pensamiento de la API de Ollama para un modelo específico configurado. OpenClaw preserva esos parámetros explícitos del modelo cuando la ejecución activa solo tiene el off predeterminado implícito; los comandos de tiempo de ejecución no desactivados, como /think medium, aún anulan la ejecución activa.

Modelos de razonamiento

OpenClaw trata los modelos con nombres como deepseek-r1, reasoning o think como capaces de razonamiento de forma predeterminada.

Ventana de terminal
ollama pull deepseek-r1:32b

No se necesita configuración adicional. OpenClaw los marca automáticamente.

Costos del modelo

Ollama es gratuito y se ejecuta localmente, por lo que todos los costos del modelo se establecen en $0. Esto se aplica tanto a los modelos descubiertos automáticamente como a los definidos manualmente.

Incrustaciones de memoria

El complemento Ollama incluido registra un proveedor de incrustaciones de memoria para búsqueda de memoria. Utiliza la URL base configurada de Ollama y la clave de API, llama al endpoint actual de Ollama /api/embed y agrupa múltiples fragmentos de memoria en una sola solicitud input cuando es posible.

Cuando proxy.enabled=true, las solicitudes de incrustación de memoria de Ollama al origen de bucle local host exacto derivado del baseUrl configurado utilizan la ruta directa protegida de OpenClaw en lugar del proxy de reenvío administrado. El nombre de host configurado debe ser localhost o una IP literal de bucle local; los nombres DNS que simplemente resuelven al bucle local aún usan la ruta del proxy administrado. Los hosts de Ollama de LAN, tailnet, red privada y pública también se mantienen en la ruta del proxy administrado. Los redireccionamientos a otro host o puerto no heredan la confianza. Los operadores aún pueden configurar el ajuste global proxy.loopbackMode: "proxy" para enviar tráfico de bucle local a través del proxy, o proxy.loopbackMode: "block" para denegar conexiones de bucle local antes de abrir una conexión; consulte Proxy administrado para el efecto en todo el proceso de este ajuste.

PropiedadValor
Modelo por defectonomic-embed-text
Auto-pullSí: el modelo de incrustación se extrae automáticamente si no está presente localmente

Las incrustaciones en el tiempo de consulta utilizan prefijos de recuperación para modelos que los requieren o recomiendan, incluyendo nomic-embed-text, qwen3-embedding y mxbai-embed-large. Los lotes de documentos de memoria permanecen sin procesar para que los índices existentes no necesiten una migración de formato.

Para seleccionar Ollama como proveedor de incrustaciones para la búsqueda de memoria:

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "ollama",
        remote: {
          // Default for Ollama. Raise on larger hosts if reindexing is too slow.
          nonBatchConcurrency: 1,
        },
      },
    },
  },
}

Para un host de incrustación remoto, mantenga la autenticación limitada a ese host:

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "ollama",
        model: "nomic-embed-text",
        remote: {
          baseUrl: "http://gpu-box.local:11434",
          apiKey: "ollama-local",
          nonBatchConcurrency: 2,
        },
      },
    },
  },
}
Configuración de streaming

La integración de OpenClaw con Ollama utiliza la API nativa de Ollama (/api/chat) de forma predeterminada, lo que admite completamente el streaming y las llamadas a herramientas simultáneamente. No se necesita ninguna configuración especial.

Para las solicitudes nativas de /api/chat, OpenClaw también reenvía el control de pensamiento directamente a Ollama: /think off y openclaw agent --thinking off envían think: false de nivel superior a menos que se configure un valor explícito de modelo params.think/params.thinking, mientras que /think low|medium|high envían la cadena de esfuerzo think de nivel superior correspondiente. /think max se asigna al esfuerzo nativo más alto de Ollama, think: "high".

Solución de problemas

Sección titulada «Solución de problemas»
Bucle de bloqueo de WSL2 (reinicio repetido)

En WSL2 con NVIDIA/CUDA, el instalador oficial de Ollama para Linux crea una unidad ollama.service systemd con Restart=always. Si ese servicio se inicia automáticamente y carga un modelo respaldado por GPU durante el arranque de WSL2, Ollama puede fijar la memoria del host mientras se carga el modelo. La recuperación de memoria de Hyper-V no siempre puede recuperar esas páginas fijadas, por lo que Windows puede terminar la máquina virtual WSL2, systemd inicia Ollama nuevamente y el bucle se repite.

Evidencias comunes:

  • reinicios o terminaciones repetidas de WSL2 desde el lado de Windows
  • alto uso de CPU en app.slice o ollama.service poco después del inicio de WSL2
  • SIGTERM de systemd en lugar de un evento de OOM-killer de Linux

OpenClaw registra una advertencia de inicio cuando detecta WSL2, ollama.service habilitado con Restart=always y marcadores CUDA visibles.

Mitigación:

Ventana de terminal
sudo systemctl disable ollama

Agregue esto a %USERPROFILE%\.wslconfig en el lado de Windows y luego ejecute wsl --shutdown:

[experimental]
autoMemoryReclaim=disabled

Configure un keep-alive más corto en el entorno del servicio Ollama, o inicie Ollama manualmente solo cuando lo necesite:

Ventana de terminal
export OLLAMA_KEEP_ALIVE=5m
ollama serve

Consulte ollama/ollama#11317.

Ollama no detectado

Asegúrese de que Ollama se esté ejecutando y de que haya configurado OLLAMA_API_KEY (o un perfil de autenticación), y de que no haya definido una entrada models.providers.ollama explícita:

Ventana de terminal
ollama serve

Verifique que la API sea accesible:

Ventana de terminal
curl http://localhost:11434/api/tags
No hay modelos disponibles

Si su modelo no está listado, descargue el modelo localmente o defínalo explícitamente en models.providers.ollama.

Ventana de terminal
ollama list  # See what's installed
ollama pull gemma4
ollama pull gpt-oss:20b
ollama pull llama3.3     # Or another model
Conexión rechazada

Compruebe que Ollama se esté ejecutando en el puerto correcto:

Ventana de terminal
# Check if Ollama is running
ps aux | grep ollama


# Or restart Ollama
ollama serve
El host remoto funciona con curl pero no con OpenClaw

Verifique desde la misma máquina y tiempo de ejecución que ejecuta el Gateway:

Ventana de terminal
openclaw gateway status --deep
curl http://ollama-host:11434/api/tags

Causas comunes:

  • baseUrl apunta a localhost, pero el Gateway se ejecuta en Docker o en otro host.
  • La URL usa /v1, lo que selecciona el comportamiento compatible con OpenAI en lugar de Ollama nativo.
  • El host remoto necesita cambios en el firewall o en el enlace de LAN en el lado de Ollama.
  • El modelo está presente en el demonio de su laptop pero no en el demonio remoto.
El modelo genera JSON de herramientas como texto

Esto generalmente significa que el proveedor está usando el modo compatible con OpenAI o que el modelo no puede manejar esquemas de herramientas.

Prefiera el modo Ollama nativo:

{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://ollama-host:11434",
        api: "ollama",
      },
    },
  },
}

Si un modelo local pequeño todavía falla en los esquemas de herramientas, establezca compat.supportsTools: false en esa entrada de modelo y pruebe de nuevo.

Kimi o GLM devuelven símbolos ilegibles

Las respuestas alojadas de Kimi/GLM que son secuencias largas de símbolos no lingüísticos se tratan como salida fallida del proveedor en lugar de una respuesta exitosa del asistente. Esto permite que la gestión normal de reintentos, respaldo o errores tome el control sin persistir el texto corrupto en la sesión.

Si sucede repetidamente, capture el nombre sin procesar del modelo, el archivo de sesión actual y si la ejecución usó Cloud + Local o Cloud only, luego intente una sesión nueva y un modelo de respaldo:

Ventana de terminal
openclaw infer model run --model ollama/kimi-k2.5:cloud --prompt "Reply with exactly: ok" --json
openclaw models set ollama/gemma4
El modelo local en frío agota el tiempo de espera

Los modelos locales grandes pueden necesitar una primera carga larga antes de que comience el streaming. Mantenga el tiempo de espera limitado al proveedor Ollama y, opcionalmente, pida a Ollama que mantenga el modelo cargado entre turnos:

{
  models: {
    providers: {
      ollama: {
        timeoutSeconds: 300,
        models: [
          {
            id: "gemma4:26b",
            name: "gemma4:26b",
            params: { keep_alive: "15m" },
          },
        ],
      },
    },
  },
}

Si el host mismo es lento para aceptar conexiones, timeoutSeconds también extiende el tiempo de espera de conexión protegido de Undici para este proveedor.

El modelo de contexto grande es demasiado lento o se queda sin memoria

Muchos modelos de Ollama anuncian contextos que son más grandes de lo que su hardware puede ejecutar cómodamente. Ollama nativo utiliza el contexto de ejecución predeterminado de Ollama a menos que configure params.num_ctx. Limite tanto el presupuesto de OpenClaw como el contexto de solicitud de Ollama cuando desee una latencia predecible del primer token:

{
  models: {
    providers: {
      ollama: {
        contextWindow: 32768,
        maxTokens: 8192,
        models: [
          {
            id: "qwen3.5:9b",
            name: "qwen3.5:9b",
            params: { num_ctx: 32768, thinking: false },
          },
        ],
      },
    },
  },
}

Reduzca contextWindow primero si OpenClaw está enviando demasiado prompt. Reduzca params.num_ctx si Ollama está cargando un contexto de ejecución que es demasiado grande para la máquina. Reduzca maxTokens si la generación tarda demasiado.

Relacionado

Sección titulada «Relacionado»
Proveedores de modelos

Resumen de todos los proveedores, referencias de modelos y comportamiento de conmutación por error.

Selección de modelo

Cómo elegir y configurar modelos.

Búsqueda web de Ollama

Detalles completos de configuración y comportamiento para la búsqueda web impulsada por Ollama.

Configuración

Referencia completa de configuración.