Ollama

OpenClaw se comunica con la API nativa de Ollama (/api/chat), no con el endpoint compatible con OpenAI /v1. Se admiten tres modos:

Modo	Qué utiliza
Nube + local	Un host de Ollama accesible que sirve modelos locales y, si se ha iniciado sesión, modelos `:cloud`
Solo nube	`https://ollama.com` directamente, sin daemon local
Solo local	Un host de Ollama accesible, únicamente modelos locales

Para configurar solo la nube con el id de proveedor dedicado ollama-cloud, consulte Ollama Cloud. Use referencias ollama-cloud/<model> cuando quiera mantener el enrutamiento en la nube separado de un proveedor local ollama.

No use la URL compatible con OpenAI /v1 (http://host:11434/v1). Interrumpe las llamadas a herramientas y los modelos pueden emitir el JSON sin procesar de las llamadas a herramientas como texto sin formato. Use la URL nativa: baseUrl: "http://host:11434" (sin /v1).

La clave de configuración canónica es baseUrl. También se acepta baseURL para ejemplos con el estilo del SDK de OpenAI, pero las configuraciones nuevas deben usar baseUrl.

Reglas de autenticación

Hosts locales y de LAN

Las URL de Ollama de bucle invertido, red privada, .local y nombre de host simple no necesitan un token de portador real. OpenClaw usa el marcador ollama-local para ellas.

Hosts remotos y de Ollama Cloud

Los hosts remotos públicos y https://ollama.com requieren una credencial real: OLLAMA_API_KEY, un perfil de autenticación o el apiKey del proveedor. Para el uso alojado directo, se recomienda el proveedor ollama-cloud.

Ids de proveedor personalizados

Un proveedor personalizado con api: "ollama" sigue las mismas reglas. Por ejemplo, un proveedor ollama-remote que apunte a un host de LAN privado puede usar apiKey: "ollama-local"; los subagentes resuelven ese marcador mediante el hook del proveedor de Ollama en lugar de tratarlo como una credencial ausente. memory.search.provider también puede apuntar a un id de proveedor personalizado para que las incrustaciones usen ese endpoint de Ollama.

Perfiles de autenticación

auth-profiles.json almacena la credencial de un id de proveedor; coloque la configuración del endpoint (baseUrl, api, modelos, encabezados y tiempos de espera) en models.providers.<id>. Los archivos planos antiguos como { "ollama-windows": { "apiKey": "ollama-local" } } no son un formato de tiempo de ejecución; openclaw doctor --fix los reescribe como un perfil canónico de clave de API ollama-windows:default con una copia de seguridad. Un valor baseUrl en ese archivo heredado es irrelevante y debe trasladarse a la configuración del proveedor.

Ámbito de las incrustaciones de memoria

La autenticación mediante portador para las incrustaciones de memoria de Ollama se limita al host para el que se declaró:

Una clave de nivel de proveedor se envía únicamente al host de ese proveedor.
memory.search.remote.apiKey y las anulaciones por agente se envían únicamente a su host remoto de incrustaciones.
Un valor de entorno OLLAMA_API_KEY puro se trata como la convención de Ollama Cloud y no se envía de forma predeterminada a hosts locales o autoalojados.

Primeros pasos

Incorporación (recomendada)
Configuración manual

Ejecutar la incorporación

openclaw onboard

Seleccione Ollama y, a continuación, elija un modo: Nube + local, Solo nube o Solo local.En una configuración guiada nueva, OpenClaw comprueba primero el host de Ollama predeterminado o configurado. Solo se ofrece automáticamente un modelo instalado cuando /api/show confirma la compatibilidad con herramientas y una ventana de contexto de al menos 16K; si faltan los metadatos de contexto o indican un tamaño menor, se mantiene la ruta de configuración manual. La secuencia de configuración compartida de CLI/macOS sigue verificando la ruta seleccionada mediante una finalización real antes de guardarla. Esta comprobación automática nunca descarga un modelo; si no existe ningún modelo instalado adecuado, la incorporación continúa con el selector normal de Ollama.

Seleccionar un modelo

Cloud only solicita OLLAMA_API_KEY y sugiere valores predeterminados alojados en la nube. Cloud + Local y Local only solicitan una URL base de Ollama, detectan los modelos disponibles y descargan automáticamente el modelo local seleccionado si falta. Una etiqueta :latest instalada, como gemma4:latest, se muestra una sola vez en lugar de duplicar gemma4. Cloud + Local también comprueba si se ha iniciado sesión en el host para acceder a la nube.

Verificar

openclaw models list --provider ollama

No interactivo:

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

--custom-base-url y --custom-model-id son opcionales; si se omiten, se utilizan el host local predeterminado y el modelo sugerido gemma4.

Instalar e iniciar Ollama

Descárguelo de ollama.com/download y, a continuación, descargue un modelo:

ollama pull gemma4

Para el acceso híbrido a la nube, ejecute ollama signin en el mismo host.

Establecer una credencial

export OLLAMA_API_KEY="ollama-local"    # host local/de LAN, funciona cualquier valor
export OLLAMA_API_KEY="your-real-key"   # solo https://ollama.com

O en la configuración: openclaw config set models.providers.ollama.apiKey "OLLAMA_API_KEY".

Seleccionar el modelo

openclaw models list
openclaw models set ollama/gemma4

O en la configuración:

{
  agents: {
    defaults: {
      model: { primary: "ollama/gemma4" },
    },
  },
}

Modelos en la nube mediante un host local

Cloud + Local enruta tanto los modelos locales como los modelos :cloud mediante un único host de Ollama accesible; este es el flujo híbrido de Ollama y el modo que se debe elegir durante la configuración cuando se desean ambos. OpenClaw solicita la URL base, detecta los modelos locales y comprueba el estado de ollama signin. Cuando se ha iniciado sesión, sugiere valores predeterminados alojados (kimi-k2.5:cloud, minimax-m2.7:cloud, glm-5.1:cloud, glm-5.2:cloud). Si no se ha iniciado sesión, la configuración permanece en modo exclusivamente local hasta que se ejecuta ollama signin. Para acceder únicamente a la nube sin un daemon local, use openclaw onboard --auth-choice ollama-cloud y consulte Ollama Cloud; esa ruta no necesita ollama signin ni un servidor en ejecución:

openclaw onboard --auth-choice ollama-cloud
openclaw models set ollama-cloud/kimi-k2.5:cloud

La lista de modelos en la nube que se muestra durante openclaw onboard se obtiene en tiempo real de https://ollama.com/api/tags y está limitada a 500 entradas, por lo que el selector refleja el catálogo alojado actual. Si no se puede acceder a ollama.com o no devuelve modelos durante la configuración, OpenClaw recurre a su lista codificada de sugerencias para que la incorporación pueda completarse.

Detección de modelos (proveedor implícito)

Cuando se establece OLLAMA_API_KEY (o un perfil de autenticación) y no se ha definido ni models.providers.ollama ni otro proveedor personalizado con api: "ollama", OpenClaw detecta los modelos desde http://127.0.0.1:11434:

Comportamiento	Detalle
Consulta del catálogo	`/api/tags`
Detección de capacidades	La lectura de mejor esfuerzo `/api/show` consulta `contextWindow`, los parámetros del Modelfile `num_ctx` y las capacidades (visión/herramientas/razonamiento)
Modelos de visión	Una capacidad `vision` de `/api/show` marca el modelo como compatible con imágenes (`input: ["text", "image"]`)
Detección de razonamiento	Usa la capacidad `thinking` de `/api/show` cuando está disponible; si Ollama omite las capacidades, recurre a una heurística basada en el nombre (`r1`, `reason`, `reasoning`, `think`). `glm-5.2:cloud` y `deepseek-v4-flash\|pro:cloud` siempre se tratan como modelos de razonamiento, independientemente de las capacidades declaradas.
Límites de tokens	`maxTokens` utiliza de forma predeterminada el límite máximo de tokens de Ollama de OpenClaw
Costes	Todos los costes son `0`

ollama list
openclaw models list

Establecer models.providers.ollama con una matriz models explícita, o un proveedor personalizado con api: "ollama" y un baseUrl que no sea de bucle invertido, desactiva la detección automática; en ese caso, los modelos deben definirse manualmente (consulte Configuración). Una entrada models.providers.ollama que apunte al https://ollama.com alojado también omite la detección, ya que los modelos de Ollama Cloud los administra el proveedor. Los proveedores personalizados de bucle invertido, como http://127.0.0.2:11434, siguen considerándose locales y mantienen la detección automática. Se puede usar una referencia completa como ollama/<pulled-model>:latest sin una entrada models.json escrita manualmente; OpenClaw la resuelve en tiempo real. En los hosts con sesión iniciada, seleccionar una referencia ollama/<model>:cloud que no figure en la lista valida ese modelo exacto mediante /api/show y lo añade al catálogo de tiempo de ejecución únicamente si Ollama confirma los metadatos; los errores tipográficos siguen produciendo un error de modelo desconocido.

Pruebas de humo

Para una prueba de texto específica que omita toda la superficie de herramientas del agente:

OLLAMA_API_KEY=ollama-local \
  openclaw infer model run \
    --local \
    --model ollama/llama3.2:latest \
    --prompt "Responde exactamente: pong" \
    --json

Añada --file con una imagen para realizar una prueba ligera de un modelo de visión (admite PNG/JPEG/WebP; los archivos que no sean imágenes se rechazan antes de llamar a Ollama; use openclaw infer audio transcribe para audio):

OLLAMA_API_KEY=ollama-local \
  openclaw infer model run \
    --local \
    --model ollama/qwen2.5vl:7b \
    --prompt "Describe esta imagen en una oración." \
    --file ./photo.jpg \
    --json

Ninguna de las dos rutas carga herramientas de chat, memoria ni contexto de sesión. Si funciona mientras fallan las respuestas normales del agente, es probable que el problema sea la capacidad del modelo para usar herramientas o actuar como agente, no el endpoint. Seleccionar un modelo con /model ollama/<model> es una elección exacta del usuario: si no se puede acceder al baseUrl configurado, la siguiente respuesta falla con el error del proveedor en lugar de recurrir silenciosamente a otro modelo configurado. Los trabajos Cron aislados añaden una comprobación de seguridad local antes de iniciar el turno del agente: si el modelo seleccionado se resuelve como un proveedor Ollama de red local/privada/.local y no se puede acceder a /api/tags, OpenClaw registra esa ejecución como skipped con el modelo en el texto del error. Esta comprobación del endpoint se almacena en caché durante 5 minutos por host, para que los trabajos Cron repetidos contra un daemon detenido no inicien todos solicitudes que fallen. Verificación en vivo:

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

Para Ollama Cloud, dirija la misma prueba en vivo al endpoint alojado (omite los embeddings de forma predeterminada; fuércelos con OPENCLAW_LIVE_OLLAMA_EMBEDDINGS=1, ya que una clave de la nube puede no autorizar /api/embed):

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

Para añadir un modelo, descárguelo y se detectará automáticamente:

ollama pull mistral

Inferencia local en el Node

Los agentes pueden delegar una tarea breve a un modelo de Ollama en un equipo de escritorio o Node de servidor emparejado. El prompt y la respuesta atraviesan la conexión autenticada existente entre el Gateway y el Node; la solicitud se ejecuta en el endpoint Ollama de bucle invertido del propio Node (http://127.0.0.1:11434).

Iniciar Ollama en el Node

ollama pull qwen3:0.6b
ollama list

Conectar el host del Node

openclaw node run \
  --host <gateway-host> \
  --port 18789 \
  --display-name "Local inference"

Apruebe el dispositivo y sus comandos del Node en el host del Gateway y, a continuación, verifique:

openclaw devices list
openclaw devices approve <deviceRequestId>
openclaw nodes pending
openclaw nodes approve <nodeRequestId>
openclaw nodes status --connected

Una primera conexión, o una actualización que añada comandos de Ollama, puede activar la aprobación de comandos del Node. Si el Node se conecta sin anunciar ollama.models y ollama.chat, vuelva a comprobar openclaw nodes pending.

Usarlo desde un agente

El plugin Ollama incluido expone la herramienta node_inference. Los agentes llaman primero a action: "discover" y, después, a action: "run" con un Node y un modelo del resultado (run puede omitir el Node cuando hay exactamente un Node compatible conectado). Por ejemplo: «Detecta los modelos de Ollama en mis Nodes y, después, usa el modelo cargado más rápido para resumir este texto».

La detección lee /api/tags, comprueba las capacidades de /api/show y usa /api/ps cuando está disponible para priorizar los modelos ya cargados. Solo devuelve los modelos locales que Ollama indica que admiten chat (capacidad completion) — se excluyen las filas de Ollama Cloud y los modelos exclusivos para embeddings. Cada ejecución desactiva el razonamiento del modelo y limita de forma predeterminada la salida a 512 tokens (límite estricto de 8192), salvo que la llamada a la herramienta solicite un maxTokens diferente; algunos modelos (por ejemplo, GPT-OSS) no permiten desactivar el razonamiento y pueden seguir emitiendo tokens de razonamiento. Para mantener Ollama en ejecución en un Node sin exponerlo a los agentes:

openclaw config set plugins.entries.ollama.config.nodeInference.enabled false

Reinicie el Node (openclaw node restart, o detenga y vuelva a ejecutar openclaw node run para una sesión en primer plano). El Node deja de anunciar ollama.models y ollama.chat; Ollama y el proveedor Ollama del Gateway no se ven afectados. Vuelva a establecer el valor en true y reinicie para reactivarlo; puede ser necesario volver a aprobar con openclaw nodes pending una superficie de comandos modificada tras reconectarse. Verifique directamente los comandos del Node, sin un turno del agente:

openclaw nodes invoke \
  --node "Local inference" \
  --command ollama.models \
  --params '{}' \
  --invoke-timeout 90000 \
  --timeout 100000

openclaw nodes invoke \
  --node "Local inference" \
  --command ollama.chat \
  --params '{"model":"qwen3:0.6b","prompt":"Responde exactamente con: pong","maxTokens":32,"timeoutMs":120000}' \
  --invoke-timeout 130000 \
  --timeout 140000

--invoke-timeout limita el tiempo que tiene el Node para ejecutar el comando; --timeout limita la llamada global al Gateway y debe ser mayor. La inferencia local en el Node siempre usa el endpoint de bucle invertido del propio Node; no reutiliza un models.providers.ollama.baseUrl remoto o en la nube configurado. Los comandos del Node están disponibles de forma predeterminada en hosts de Node macOS, Linux y Windows y siguen sujetos a la política normal de emparejamiento y comandos del Node.

Visión y descripción de imágenes

El plugin Ollama incluido registra Ollama como proveedor de comprensión de medios compatible con imágenes, por lo que OpenClaw puede enrutar las solicitudes explícitas de descripción de imágenes y los valores predeterminados configurados del modelo de imágenes a través de modelos de visión de Ollama locales o alojados.

ollama pull qwen2.5vl:7b
export OLLAMA_API_KEY="ollama-local"
openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --json

--model debe ser una referencia <provider/model> completa; cuando se establece, infer image describe prueba primero ese modelo en lugar de omitir la descripción para los modelos que ya admiten visión nativa. Si la llamada falla, OpenClaw puede continuar mediante agents.defaults.imageModel.fallbacks; los errores de preparación de archivos o URL fallan antes de intentar el fallback. Use infer image describe para el flujo de comprensión de imágenes de OpenClaw y el imageModel configurado; use infer model run --file para una prueba multimodal directa con un prompt personalizado. Para convertir Ollama en el proveedor predeterminado de comprensión de imágenes para medios entrantes:

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

Se recomienda la referencia ollama/<model> completa. Una referencia imageModel simple como qwen2.5vl:7b se normaliza a ollama/qwen2.5vl:7b solo cuando ese modelo exacto aparece en models.providers.ollama.models con input: ["text", "image"] y ningún otro proveedor de imágenes configurado expone el mismo identificador simple; de lo contrario, 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 y pueden bloquearse en hardware con recursos limitados si Ollama intenta asignar el contexto de visión anunciado completo del modelo. Establezca un tiempo de espera de capacidad y limite num_ctx:

{
  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. models.providers.ollama.timeoutSeconds sigue controlando la protección de la solicitud HTTP subyacente de Ollama para las llamadas normales al modelo. Verificación en vivo:

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 explícitamente los modelos de visión:

{
  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 no marcados como compatibles con imágenes. Con la detección implícita, esto procede de la capacidad de visión de /api/show.

Configuración

Básica (detección implícita)
Explícita (modelos manuales)
URL base personalizada

export OLLAMA_API_KEY="ollama-local"

Si se establece OLLAMA_API_KEY, puede omitir apiKey en la entrada del proveedor; OpenClaw lo rellena para las comprobaciones de disponibilidad.

Use una configuración explícita para una instalación alojada en la nube, un host o puerto no predeterminado, ventanas de contexto forzadas o listas de modelos completamente manuales:

{
  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"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 8192
          }
        ]
      }
    }
  }
}

La configuración explícita desactiva la detección automática, por lo que deben enumerarse los modelos:

{
  models: {
    providers: {
      ollama: {
        apiKey: "ollama-local",
        baseUrl: "http://ollama-host:11434", // Sin /v1: URL de la API nativa de Ollama
        api: "ollama", // Explícito: garantiza el comportamiento nativo de llamada a herramientas
        timeoutSeconds: 300, // Opcional: presupuesto de conexión/transmisión más largo para modelos locales en frío
        models: [
          {
            id: "qwen3:32b",
            name: "qwen3:32b",
            params: {
              keep_alive: "15m", // Opcional: mantiene el modelo cargado entre turnos
            },
          },
        ],
      },
    },
  },
}

No añada /v1. Esa ruta selecciona el modo compatible con OpenAI, en el que las llamadas a herramientas no son fiables.

Recetas habituales

Sustituya los identificadores de modelo por los nombres exactos de ollama list o openclaw models list --provider ollama.

Modelo local con detección automática

Ollama en el mismo equipo que el Gateway, detectado automáticamente:

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

No añada un bloque models.providers.ollama a menos que necesite modelos manuales.

Host de Ollama en la LAN con modelos manuales

{
  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 de OpenClaw; params.num_ctx se envía a Ollama. Manténgalos alineados cuando el hardware no pueda ejecutar todo el contexto anunciado del modelo.

Solo Ollama Cloud

Sin daemon local, modelos alojados directamente:

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" },
    },
  },
}

Para usar el id de proveedor dedicado ollama-cloud en lugar de esta estructura, consulte Ollama Cloud.

Nube y entorno local mediante un daemon con sesión iniciada

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"],
      },
    },
  },
}

Varios hosts de Ollama

Use ids de proveedor personalizados cuando ejecute más de un servidor Ollama; cada uno obtiene su propio host, modelos, autenticación y tiempo de espera.

{
  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"],
      },
    },
  },
}

OpenClaw elimina el prefijo del proveedor activo (y recurre a un prefijo ollama/ simple) antes de llamar a Ollama, por lo que ollama-large/qwen3.5:27b llega a Ollama como qwen3.5:27b.

Perfil ligero de modelo local

Algunos modelos locales gestionan instrucciones sencillas, pero tienen dificultades con la superficie completa de herramientas del agente. Limite las herramientas y el contexto antes de modificar la configuración global del entorno 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 únicamente cuando el modelo o el servidor falle de forma sistemática con los esquemas de herramientas; esto sacrifica capacidad del agente a cambio de estabilidad. localModelLean elimina las herramientas pesadas de navegador, Cron, mensajería, generación de contenido multimedia, voz y PDF de la superficie directa del agente, salvo que se requieran explícitamente, y coloca los catálogos más grandes detrás de la búsqueda de herramientas. No cambia el contexto de ejecución ni el modo de razonamiento de Ollama. Combínelo con params.num_ctx y params.thinking: false para modelos pequeños de razonamiento al estilo Qwen que entran en bucle o consumen su presupuesto en razonamiento oculto.

Selección de modelos

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

Los ids de proveedor personalizados funcionan de la misma manera: para una referencia que use el prefijo del proveedor activo, como ollama-spark/qwen3:32b, OpenClaw elimina ese prefijo antes de llamar a Ollama y envía qwen3:32b. Para modelos locales lentos, es preferible ajustar el proveedor antes de aumentar el tiempo de espera de todo el entorno de ejecución del agente:

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

timeoutSeconds abarca la solicitud HTTP del modelo: establecimiento de la conexión, encabezados, transmisión del cuerpo y cancelación total de la solicitud protegida. params.keep_alive se reenvía como keep_alive de nivel superior en las solicitudes nativas /api/chat; configúrelo por modelo cuando el tiempo de carga del primer turno sea el cuello de botella.

Verificación rápida

# Daemon de Ollama visible para esta máquina
curl http://127.0.0.1:11434/api/tags

# Catálogo de OpenClaw y modelo seleccionado
openclaw models list --provider ollama
openclaw models status

# Prueba de humo directa del modelo
openclaw infer model run \
  --model ollama/gemma4 \
  --prompt "Responde exactamente con: ok"

Para hosts remotos, sustituya 127.0.0.1 por el host baseUrl. Si curl funciona, pero OpenClaw no, compruebe si el Gateway se ejecuta en otra máquina, contenedor o cuenta de servicio.

Búsqueda web de Ollama

OpenClaw incluye Búsqueda web de Ollama como proveedor web_search.

Propiedad	Detalle
Host	`models.providers.ollama.baseUrl` cuando se establece; de lo contrario, `http://127.0.0.1:11434`; `https://ollama.com` usa directamente la API alojada
Autenticación	Sin clave para un host local con sesión iniciada; `OLLAMA_API_KEY` o la autenticación configurada del proveedor para búsquedas directas en `https://ollama.com` o hosts protegidos mediante autenticación
Requisito	Los hosts locales o autoalojados deben estar en ejecución y tener una sesión iniciada con `ollama signin`; la búsqueda alojada directa requiere `baseUrl: "https://ollama.com"` y una clave de API real

Elíjalo durante openclaw onboard o openclaw configure --section web, o establezca:

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

Para realizar búsquedas alojadas directas mediante 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 host autoalojado, OpenClaw primero intenta usar el proxy local /api/experimental/web_search y, a continuación, recurre a la ruta alojada /api/web_search del mismo host; normalmente, un daemon local con sesión iniciada responde mediante el proxy local. Las llamadas directas a https://ollama.com siempre usan el endpoint alojado /api/web_search.

Para obtener información completa sobre la configuración y el comportamiento, consulte Búsqueda web de Ollama.

Configuración avanzada

Modo heredado compatible con OpenAI

Las llamadas a herramientas no son fiables en este modo. Úselo únicamente cuando un proxy necesite el formato de OpenAI y no dependa de llamadas nativas a herramientas.

Establezca api: "openai-completions" explícitamente para un proxy detrás de /v1/chat/completions:

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

Es posible que este modo no admita simultáneamente la transmisión y las llamadas a herramientas; puede que necesite params: { streaming: false } en el modelo.OpenClaw inyecta options.num_ctx de forma predeterminada en este modo para que Ollama no recurra silenciosamente a un contexto de 4096 tokens. Si el proxy rechaza campos options desconocidos, desactívelo:

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

Ventanas de contexto

Para los modelos detectados automáticamente, OpenClaw usa la ventana de contexto que /api/show notifica, incluidos los valores PARAMETER num_ctx más grandes de Modelfiles personalizados; de lo contrario, recurre a la ventana de contexto predeterminada de Ollama en OpenClaw.Los valores contextWindow, contextTokens y maxTokens del proveedor establecen los valores predeterminados de todos los modelos de ese proveedor y pueden sobrescribirse para cada modelo. contextWindow es el presupuesto de instrucciones y Compaction propio de OpenClaw. Las solicitudes nativas /api/chat dejan options.num_ctx sin establecer, salvo que se configure params.num_ctx explícitamente, por lo que Ollama aplica su propio valor predeterminado basado en el modelo, OLLAMA_CONTEXT_LENGTH o la VRAM; se ignoran los valores params.num_ctx no válidos, iguales a cero, negativos o no finitos. Si una configuración anterior usaba únicamente contextWindow/maxTokens para forzar el contexto de la solicitud nativa, ejecute openclaw doctor --fix para copiarlos en params.num_ctx. El adaptador compatible con OpenAI sigue inyectando options.num_ctx de forma predeterminada a partir de los valores configurados params.num_ctx o contextWindow; desactívelo con injectNumCtxForOpenAICompat: false si el servicio de origen rechaza options.Las entradas de modelos nativos también aceptan opciones habituales del entorno de ejecución de Ollama en params, que se reenvían como /api/chat options nativos: num_keep, seed, num_predict, top_k, top_p, min_p, typical_p, repeat_last_n, temperature, repeat_penalty, presence_penalty, frequency_penalty, stop, num_batch, num_gpu, main_gpu, use_mmap y num_thread. Algunas claves (format, keep_alive, truncate, shift) se reenvían como campos de solicitud de nivel superior en lugar de estar anidadas en options. OpenClaw solo reenvía estas claves de solicitud de Ollama, por lo que los parámetros exclusivos del entorno de ejecución, como streaming, nunca se envían a Ollama. Use params.think (o params.thinking) para establecer think en el nivel superior; false desactiva el razonamiento en el nivel de la API para los modelos de razonamiento al 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,
            },
          }
        ]
      }
    }
  }
}

La configuración por modelo agents.defaults.models["ollama/<model>"].params.num_ctx también funciona; la entrada explícita del modelo del proveedor prevalece si se configuran ambas.

Control del razonamiento

OpenClaw reenvía el razonamiento como lo espera Ollama: think en el nivel superior, no options.think. Los modelos detectados automáticamente cuyo /api/show informa de una capacidad thinking exponen /think low, /think medium, /think high y /think max; los modelos sin razonamiento solo exponen /think off.

openclaw agent --model ollama/gemma4 --thinking off
openclaw agent --model ollama/gemma4 --thinking low

También se puede establecer un valor predeterminado para el modelo:

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

La configuración por modelo params.think/params.thinking puede desactivar o forzar el razonamiento de la API para un modelo específico. OpenClaw conserva esa configuración explícita cuando la ejecución activa solo tiene el valor predeterminado implícito off; un comando de ejecución distinto de «desactivado», como /think medium, sigue prevaleciendo. Nunca se envía una solicitud de razonamiento verdadera a un modelo marcado explícitamente como reasoning: false; una solicitud think: false se envía siempre.

Modelos de razonamiento

Los modelos denominados deepseek-r1, reasoning, reason o think se consideran compatibles con el razonamiento de forma predeterminada; no se necesita ninguna configuración adicional:

ollama pull deepseek-r1:32b

Costes de los modelos

Ollama se ejecuta localmente y es gratuito, por lo que todos los costes de los modelos son 0, tanto para los modelos detectados automáticamente como para los definidos manualmente.

Embeddings de memoria

El plugin de Ollama incluido registra un proveedor de embeddings de memoria para la búsqueda en memoria. Utiliza la URL base y la clave de API de Ollama configuradas, llama a /api/embed y agrupa varios fragmentos de memoria en una solicitud input cuando es posible.Cuando proxy.enabled=true, las solicitudes de embeddings al origen de bucle invertido local del host exacto derivado de 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 un literal de IP de bucle invertido; los nombres DNS que simplemente se resuelven a bucle invertido siguen utilizando la ruta del proxy administrado. Los hosts de Ollama de la LAN, tailnet, redes privadas y públicas siempre permanecen en la ruta del proxy administrado, y las redirecciones a otro host o puerto no heredan la confianza. proxy.loopbackMode: "proxy" enruta de todos modos el tráfico de bucle invertido a través del proxy; proxy.loopbackMode: "block" lo deniega antes de conectarse; consulte Proxy administrado.

Propiedad	Valor
Modelo predeterminado	`nomic-embed-text`
Descarga automática	Sí, si no está presente localmente
Concurrencia en línea predeterminada	1 (otros proveedores tienen valores predeterminados superiores; auméntela con `nonBatchConcurrency` si el host puede soportarlo)

Los embeddings en el momento de la consulta utilizan prefijos de recuperación para los modelos que los requieren o recomiendan: nomic-embed-text, qwen3-embedding y mxbai-embed-large. Los lotes de documentos permanecen sin procesar, por lo que los índices existentes no necesitan migrar su formato.

{
  memory: {
    search: {
      provider: "ollama",
      remote: {
        // Valor predeterminado para Ollama. Auméntelo en hosts más grandes si la reindexación es demasiado lenta.
        nonBatchConcurrency: 1,
      },
    },
  },
}

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

{
  memory: {
    search: {
      provider: "ollama",
      model: "nomic-embed-text",
      remote: {
        baseUrl: "http://gpu-box.local:11434",
        apiKey: "ollama-local",
        nonBatchConcurrency: 2,
      },
    },
  },
}

Configuración de streaming

Ollama utiliza de forma predeterminada la API nativa (/api/chat), que admite conjuntamente streaming y llamadas a herramientas; no se necesita ninguna configuración especial.En las solicitudes nativas, el control del razonamiento se reenvía directamente: /think off y openclaw agent --thinking off envían think: false en el nivel superior, salvo que se configure explícitamente params.think/params.thinking; /think low|medium|high envía la cadena de esfuerzo correspondiente; /think max se asigna al máximo esfuerzo de Ollama, think: "high".

Para utilizar en su lugar el endpoint compatible con OpenAI, consulte «Modo heredado compatible con OpenAI» más arriba; es posible que el streaming y las llamadas a herramientas no funcionen conjuntamente allí.

Solución de problemas

Bucle de fallos de WSL2 (reinicios repetidos)

En WSL2 con NVIDIA/CUDA, el instalador oficial de Ollama para Linux crea una unidad systemd ollama.service 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 memoria del host durante la carga; la recuperación de memoria de Hyper-V no siempre puede recuperar esas páginas, por lo que Windows puede finalizar la máquina virtual de WSL2, systemd reinicia Ollama y el bucle se repite.Indicios: reinicios o finalizaciones repetidos de WSL2, uso elevado de CPU en app.slice o ollama.service justo después del inicio de WSL2 y SIGTERM de systemd en lugar del eliminador por memoria insuficiente de Linux.OpenClaw registra una advertencia de inicio cuando detecta WSL2, ollama.service habilitado con Restart=always y marcadores CUDA visibles.Mitigación:

sudo systemctl disable ollama

En Windows, añada lo siguiente a %USERPROFILE%\.wslconfig y, a continuación, ejecute wsl --shutdown:

[experimental]
autoMemoryReclaim=disabled

También se puede reducir el tiempo de persistencia o iniciar Ollama manualmente solo cuando sea necesario:

export OLLAMA_KEEP_ALIVE=5m
ollama serve

Consulte ollama/ollama#11317.

Ollama no se detecta

Confirme que Ollama se esté ejecutando, que OLLAMA_API_KEY (o un perfil de autenticación) esté configurado y que models.providers.ollama no esté definido explícitamente:

ollama serve
curl http://localhost:11434/api/tags

No hay modelos disponibles

Descargue el modelo localmente o defínalo explícitamente en models.providers.ollama:

ollama list  # Consulte qué está instalado
ollama pull gemma4
ollama pull gpt-oss:20b
ollama pull llama3.3     # O bien otro modelo

Conexión rechazada

# Compruebe si Ollama se está ejecutando
ps aux | grep ollama

# O reinicie Ollama
ollama serve

El host remoto funciona con curl, pero no con OpenClaw

Verifíquelo desde la misma máquina y el mismo entorno de ejecución donde se ejecuta el Gateway:

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 utiliza /v1, lo que selecciona el comportamiento compatible con OpenAI en lugar del comportamiento nativo de Ollama.
El host remoto requiere cambios en el cortafuegos o en la vinculación a la LAN.
El modelo está en el daemon del equipo portátil, pero no en el remoto.

El modelo genera el JSON de las herramientas como texto

Normalmente, el proveedor está en modo compatible con OpenAI o el modelo no puede gestionar esquemas de herramientas. Es preferible utilizar el modo nativo:

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

Si un modelo local pequeño sigue fallando con los esquemas de herramientas, establezca compat.supportsTools: false en la entrada de ese modelo y vuelva a probarlo.

Kimi o GLM devuelve símbolos ilegibles

Las respuestas alojadas de Kimi/GLM que consisten en secuencias largas de símbolos no lingüísticos se tratan como una llamada fallida al proveedor, en lugar de como una respuesta correcta, de modo que se aplican los mecanismos normales de reintento, conmutación por error y gestión de errores en vez de conservar texto dañado en la sesión.Si vuelve a ocurrir, capture el nombre del modelo, el archivo de sesión actual y si la ejecución utilizó Cloud + Local o Cloud only; a continuación, pruebe con una sesión nueva y un modelo alternativo:

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 mucho tiempo para la primera carga. Limite el tiempo de espera al proveedor Ollama y, opcionalmente, mantenga cargado el modelo entre turnos:

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

Si el propio host tarda en aceptar conexiones, timeoutSeconds también amplía el tiempo de espera protegido de conexión para este proveedor.

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

Muchos modelos anuncian contextos mayores de lo que el hardware puede ejecutar cómodamente. Ollama nativo utiliza su propio valor predeterminado de ejecución, salvo que se establezca params.num_ctx. Limite tanto el presupuesto de OpenClaw como el contexto de solicitud de Ollama para obtener una latencia predecible hasta el 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 si OpenClaw envía demasiado contenido en el prompt. Reduzca params.num_ctx si el contexto de ejecución de Ollama es demasiado grande para la máquina. Reduzca maxTokens si la generación tarda demasiado.

Más ayuda: Solución de problemas y Preguntas frecuentes.

Temas relacionados

Ollama Cloud

Configuración exclusiva para la nube con el proveedor ollama-cloud dedicado.

Proveedores de modelos

Descripción general de todos los proveedores, las referencias de modelos y el comportamiento de conmutación por error.

Selección de modelos

Cómo elegir y configurar modelos.

Búsqueda web de Ollama

Detalles completos de la configuración y el comportamiento de la búsqueda web con tecnología de Ollama.

Configuración

Referencia completa de configuración.

Overview

Concepts and configuration

Providers

Reglas de autenticación

Primeros pasos

Modelos en la nube mediante un host local

Detección de modelos (proveedor implícito)

Pruebas de humo

Inferencia local en el Node

Visión y descripción de imágenes

Configuración

Recetas habituales

Selección de modelos

Verificación rápida

Búsqueda web de Ollama

Configuración avanzada

Solución de problemas

Temas relacionados

Ollama Cloud

Proveedores de modelos

Selección de modelos

Búsqueda web de Ollama

Configuración

​Reglas de autenticación

​Primeros pasos

​Modelos en la nube mediante un host local

​Detección de modelos (proveedor implícito)

​Pruebas de humo

​Inferencia local en el Node

​Visión y descripción de imágenes

​Configuración

​Recetas habituales

​Selección de modelos

​Verificación rápida

​Búsqueda web de Ollama

​Configuración avanzada

​Solución de problemas

​Temas relacionados

Ollama Cloud

Proveedores de modelos

Selección de modelos

Búsqueda web de Ollama

Configuración

Reglas de autenticación

Primeros pasos

Modelos en la nube mediante un host local

Detección de modelos (proveedor implícito)

Pruebas de humo

Inferencia local en el Node

Visión y descripción de imágenes

Configuración

Recetas habituales

Selección de modelos

Verificación rápida

Búsqueda web de Ollama

Configuración avanzada

Solución de problemas

Temas relacionados