Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw se integra con la API nativa de Ollama (/api/chat) para modelos en la nube alojados y servidores Ollama locales/autohospedados. Puedes usar Ollama en tres modos: Cloud + Local mediante un host de Ollama accesible, Cloud only contra https://ollama.com, o Local only contra un host de Ollama accesible.
Usuarios de Ollama remoto: No uses la URL compatible con OpenAI /v1 (http://host:11434/v1) con OpenClaw. Esto rompe la llamada a herramientas y los modelos pueden generar JSON de herramientas sin procesar como texto plano. Usa en su lugar la URL de la API nativa de Ollama: baseUrl: "http://host:11434" (sin /v1).
La configuración del proveedor de Ollama usa baseUrl como clave canónica. OpenClaw también acepta baseURL para compatibilidad con ejemplos de estilo del SDK de OpenAI, pero la configuración nueva debería preferir baseUrl.

​
Reglas de autenticación

Los hosts de Ollama locales y LAN no necesitan un token bearer real. OpenClaw usa el marcador local ollama-local solo para URLs base de Ollama de loopback, red privada, .local y nombres de host simples.
Los hosts públicos remotos y Ollama Cloud (https://ollama.com) requieren una credencial real mediante OLLAMA_API_KEY, un perfil de autenticación o el apiKey del proveedor.
Los IDs de proveedor personalizados que establecen api: "ollama" siguen las mismas reglas. Por ejemplo, un proveedor ollama-remote que apunta a un host de Ollama en una LAN privada puede usar apiKey: "ollama-local" y los subagentes resolverán ese marcador mediante el hook del proveedor de 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 embeddings usen el endpoint de Ollama correspondiente.
auth-profiles.json almacena la credencial para un ID de proveedor. Pon los ajustes del endpoint (baseUrl, api, IDs de modelo, encabezados, tiempos de espera) en models.providers.<id>. Los archivos de perfil de autenticación planos antiguos, como { "ollama-windows": { "apiKey": "ollama-local" } }, no son un formato de runtime; ejecuta openclaw doctor --fix para reescribirlos al perfil canónico de clave de API ollama-windows:default con una copia de seguridad. baseUrl en ese archivo es ruido de compatibilidad y debería moverse a la configuración del proveedor.
Cuando Ollama se usa para embeddings de memoria, la autenticación bearer se limita al host donde fue declarada:
  • Una clave de nivel de proveedor se envía solo al host de Ollama de ese proveedor.
  • agents.*.memorySearch.remote.apiKey se envía solo a su host remoto de embeddings.
  • Un valor de entorno puro OLLAMA_API_KEY se trata como la convención de Ollama Cloud, y no se envía de forma predeterminada a hosts locales o autohospedados.

​
Primeros pasos

Elige tu método y modo de configuración preferidos.
Ideal para: la ruta más rápida hacia una configuración de Ollama en la nube o local funcional.
1

Ejecuta el onboarding

openclaw onboard
Selecciona Ollama en la lista de proveedores.
2

Elige tu modo

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

Selecciona un modelo

Cloud only solicita OLLAMA_API_KEY y sugiere valores predeterminados alojados en la nube. Cloud + Local y Local only piden una URL base de Ollama, descubren los modelos disponibles y descargan automáticamente el modelo local seleccionado si todavía no está disponible. Cuando Ollama informa una etiqueta :latest instalada, como gemma4:latest, la configuración muestra ese modelo instalado una sola vez en lugar de mostrar tanto gemma4 como gemma4:latest o volver a descargar el alias simple. Cloud + Local también comprueba si ese host de Ollama tiene sesión iniciada para acceso a la nube.
4

Verifica que el modelo esté disponible

openclaw models list --provider ollama

​
Modo no interactivo

openclaw onboard --non-interactive \
  --auth-choice ollama \
  --accept-risk
Opcionalmente, especifica una URL base o un modelo personalizados:
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

Cloud + Local usa un host de 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 desde ese host y comprueba si el host tiene sesión iniciada para acceso a la nube con ollama signin. Cuando el host tiene sesión iniciada, OpenClaw también sugiere valores predeterminados alojados en la nube, como kimi-k2.5:cloud, minimax-m2.7:cloud y glm-5.1:cloud.Si el host aún no tiene sesión iniciada, OpenClaw mantiene la configuración como solo local hasta que ejecutes ollama signin.

​
Descubrimiento de modelos (proveedor implícito)

Cuando estableces OLLAMA_API_KEY (o un perfil de autenticación) y no defines 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álogoConsulta /api/tags
Detección de capacidadesUsa búsquedas de mejor esfuerzo en /api/show para leer contextWindow, parámetros Modelfile num_ctx expandidos y capacidades, incluida visión/herramientas
Modelos de visiónLos modelos con una capacidad vision informada por /api/show se marcan como compatibles con imágenes (input: ["text", "image"]), por lo que OpenClaw inyecta imágenes automáticamente en el prompt
Detección de razonamientoUsa capacidades de /api/show cuando están disponibles, incluido thinking; recurre a una heurística de nombre de modelo (r1, reasoning, think) cuando Ollama omite capacidades
Límites de tokensEstablece maxTokens en el límite predeterminado de tokens máximos de Ollama usado por OpenClaw
CostosEstablece todos los costos en 0
Esto evita entradas manuales de modelos mientras mantiene el catálogo alineado con la instancia local de Ollama. Puedes 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 a mano. Para hosts de Ollama con sesión iniciada, algunos modelos :cloud pueden ser utilizables mediante /api/chat y /api/show antes de que aparezcan en /api/tags. Cuando seleccionas explícitamente una referencia completa ollama/<model>:cloud, OpenClaw valida ese modelo faltante exacto con /api/show y lo agrega al catálogo de runtime solo si Ollama confirma los metadatos del modelo. Los errores tipográficos siguen fallando como modelos desconocidos en lugar de crearse automáticamente. 
# See what models are available
ollama list
openclaw models list
Para una prueba de humo acotada de generación de texto que evita toda la superficie de herramientas del agente, usa infer model run local con una referencia completa de modelo de Ollama: 
OLLAMA_API_KEY=ollama-local \
  openclaw infer model run \
    --local \
    --model ollama/llama3.2:latest \
    --prompt "Reply with exactly: pong" \
    --json
Esa ruta sigue usando el proveedor configurado de OpenClaw, la autenticación y el transporte nativo de Ollama, pero no inicia un turno de agente de chat ni carga contexto de MCP/herramientas. Si esto funciona mientras las respuestas normales del agente fallan, diagnostica después la capacidad del modelo para prompts de agente/herramientas. Para una prueba de humo acotada de modelo de visión en la misma ruta ligera, agrega 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 ni contexto de sesión previo: 
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/*, incluidas entradas comunes PNG, JPEG y WebP. Los archivos que no son imagen se rechazan antes de llamar a Ollama. Para reconocimiento de voz, usa openclaw infer audio transcribe en su lugar. Cuando cambias una conversación con /model ollama/<model>, OpenClaw trata eso como una selección exacta del usuario. Si el baseUrl de Ollama configurado no es accesible, la siguiente respuesta falla con el error del proveedor en lugar de responder silenciosamente desde otro modelo de respaldo configurado. Los trabajos Cron aislados realizan una comprobación de seguridad local adicional antes de iniciar el turno del agente. Si el modelo seleccionado se resuelve a un proveedor Ollama local, de red privada o .local y no se puede acceder a /api/tags, OpenClaw registra esa ejecución de Cron como skipped con el ollama/<model> seleccionado en el texto del error. La comprobación previa del endpoint se almacena en caché durante 5 minutos, por lo que varios trabajos Cron apuntados al mismo demonio Ollama detenido no lanzan todos solicitudes de modelo fallidas. Verifica en vivo la ruta de texto local, la ruta de stream nativa y los embeddings contra Ollama local con: 
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA=1 OPENCLAW_LIVE_OLLAMA_WEB_SEARCH=0 \
  pnpm test:live -- extensions/ollama/ollama.live.test.ts
Para agregar un modelo nuevo, simplemente descárgalo con Ollama: 
ollama pull mistral
El modelo nuevo se descubrirá automáticamente y estará disponible para usarlo.
Si configuras models.providers.ollama explícitamente, o configuras un proveedor remoto personalizado como models.providers.ollama-cloud con api: "ollama", se omite el descubrimiento automático y debes definir los modelos manualmente. Los proveedores personalizados de loopback como http://127.0.0.2:11434 se siguen tratando como locales. Consulta la sección de configuración explícita más abajo.

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

El Plugin Ollama incluido registra Ollama como un proveedor de comprensión de medios con capacidad para imágenes. Esto permite que OpenClaw dirija solicitudes explícitas de descripción de imágenes y valores predeterminados configurados de modelos de imagen a través de modelos de visión Ollama locales o alojados. Para visión local, descarga un modelo que admita imágenes: 
ollama pull qwen2.5vl:7b
export OLLAMA_API_KEY="ollama-local"
Luego verifica con la CLI de inferencia: 
openclaw infer image describe \
  --file ./photo.jpg \
  --model ollama/qwen2.5vl:7b \
  --json
--model debe ser una referencia completa <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. Usa infer image describe cuando quieras el flujo de proveedor de comprensión de imágenes de OpenClaw, el agents.defaults.imageModel configurado y la forma de salida de descripción de imagen. Usa infer model run --file cuando quieras una prueba multimodal sin procesar del modelo con un prompt personalizado y una o más imágenes. Para convertir Ollama en el modelo predeterminado de comprensión de imágenes para medios entrantes, configura agents.defaults.imageModel: 
{
  agents: {
    defaults: {
      imageModel: {
        primary: "ollama/qwen2.5vl:7b",
      },
    },
  },
}
Prefiere la referencia completa ollama/<model>. Si el mismo modelo figura en models.providers.ollama.models con input: ["text", "image"] y ningún otro proveedor de imágenes configurado expone ese ID de modelo sin prefijo, OpenClaw también normaliza una referencia imageModel sin prefijo como qwen2.5vl:7b a ollama/qwen2.5vl:7b. Si más de un proveedor de imágenes configurado tiene el mismo ID sin prefijo, usa el prefijo del proveedor explícitamente. Los modelos de visión locales lentos pueden necesitar un timeout de comprensión de imágenes más largo que los modelos en la nube. También pueden fallar o detenerse cuando Ollama intenta asignar todo el contexto de visión anunciado en hardware limitado. Establece un timeout de capacidad y limita num_ctx en la entrada del modelo cuando solo necesites un turno normal de descripción de imagen: 
{
  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 timeout 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. models.providers.ollama.timeoutSeconds a nivel de proveedor sigue controlando la protección de la solicitud HTTP subyacente de Ollama para llamadas normales al modelo. Verifica en vivo la herramienta explícita de imagen contra Ollama local con: 
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \
  pnpm test:live -- src/agents/tools/image-tool.ollama.live.test.ts
Si defines models.providers.ollama.models manualmente, marca los modelos de visión con compatibilidad 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 compatibles con imágenes. Con el descubrimiento implícito, OpenClaw lee esto de Ollama cuando /api/show informa una capacidad de visión.

​
Configuración

La ruta de habilitación local más sencilla es mediante variable de entorno:
export OLLAMA_API_KEY="ollama-local"
Si OLLAMA_API_KEY está establecida, puedes omitir apiKey en la entrada del proveedor y OpenClaw la completará para las comprobaciones de disponibilidad.

​
Recetas comunes

Usa estas como puntos de partida y reemplaza los ID de modelo por los nombres exactos de ollama list o openclaw models list --provider ollama.
Usa esto cuando Ollama se ejecute en la misma máquina que el Gateway y quieras que OpenClaw descubra automáticamente los modelos instalados.
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 mínima. No agregues un bloque models.providers.ollama a menos que quieras definir modelos manualmente.
Usa URL nativas de Ollama para hosts LAN. No agregues /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. Mantenlos alineados cuando tu hardware no pueda ejecutar todo el contexto anunciado del modelo.
Usa esto cuando no ejecutes un demonio local y quieras modelos Ollama 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" },
    },
  },
}
Usa esto cuando un demonio Ollama local o LAN haya iniciado sesión con ollama signin y deba servir tanto modelos locales como modelos :cloud.
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"],
      },
    },
  },
}
Usa ID de proveedores personalizados cuando tengas más de un servidor Ollama. Cada proveedor obtiene su propio host, modelos, autenticación, timeout y referencias de modelo.
{
  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 para que ollama-large/qwen3.5:27b llegue a Ollama como qwen3.5:27b.
Algunos modelos locales pueden responder prompts simples, pero tienen dificultades con toda la superficie de herramientas del agente. Empieza limitando las herramientas y el contexto antes de cambiar la configuración global del runtime.
{
  agents: {
    defaults: {
      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 },
          },
        ],
      },
    },
  },
}
Usa compat.supportsTools: false solo cuando el modelo o el servidor falla de forma fiable con los esquemas de herramientas. Intercambia capacidad del agente por estabilidad. localModelLean elimina las herramientas de 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ínalo con params.num_ctx explícito y params.thinking: false para modelos de pensamiento pequeños de estilo Qwen que entran en bucle o gastan su presupuesto de respuesta en razonamiento oculto.

​
Selección de modelo

Una vez configurados, todos tus 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 usa el prefijo del proveedor activo, como ollama-spark/qwen3:32b, OpenClaw elimina solo ese prefijo antes de llamar a Ollama para que el servidor reciba qwen3:32b. Para modelos locales lentos, prefiere el ajuste de solicitudes con ámbito de proveedor antes de aumentar el tiempo de espera de ejecución de todo el 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, incluida la configuración de la conexión, los encabezados, el streaming del cuerpo y el aborto total protegido de la obtención. params.keep_alive se reenvía a Ollama como keep_alive de nivel superior en solicitudes nativas /api/chat; configúralo por modelo cuando el tiempo de carga del primer turno sea el cuello de botella.

​
Verificación rápida

# 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, reemplaza 127.0.0.1 por el host usado en baseUrl. Si curl funciona pero OpenClaw no, comprueba si el Gateway se ejecuta en otra máquina, contenedor o cuenta de servicio.

​
Búsqueda web de Ollama

OpenClaw admite Búsqueda web de Ollama como proveedor web_search incluido.
PropiedadDetalle
HostUsa tu host de Ollama configurado (models.providers.ollama.baseUrl cuando está definido; de lo contrario, http://127.0.0.1:11434); https://ollama.com usa directamente la API alojada
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 en https://ollama.com o hosts protegidos por autenticación
RequisitoLos hosts locales/autohospedados deben estar en ejecución y con sesión iniciada mediante ollama signin; la búsqueda alojada directa requiere baseUrl: "https://ollama.com" más una clave de API real de Ollama
Elige Búsqueda web de Ollama durante openclaw onboard o openclaw configure --section web, o configura: 
{
  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 daemon local con sesión iniciada, OpenClaw usa el proxy /api/experimental/web_search del daemon. Para https://ollama.com, llama directamente al endpoint alojado /api/web_search.
Para la configuración completa y los detalles de comportamiento, consulta Búsqueda web de Ollama.

​
Configuración avanzada

La llamada a herramientas no es fiable en el modo compatible con OpenAI. Usa este modo solo si necesitas el formato de OpenAI para un proxy y no dependes del comportamiento nativo de llamada a herramientas.
Si necesitas usar en su lugar el endpoint compatible con OpenAI (por ejemplo, detrás de un proxy que solo admite el formato de OpenAI), configura 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: [...]
      }
    }
  }
}
Es posible que este modo no admita streaming y llamada a herramientas simultáneamente. Puede que tengas que desactivar el streaming con params: { streaming: false } en la configuración del modelo.Cuando api: "openai-completions" se usa con Ollama, OpenClaw inyecta options.num_ctx de forma predeterminada para que Ollama no vuelva silenciosamente a una ventana de contexto de 4096. Si tu proxy/upstream rechaza campos options desconocidos, desactiva este comportamiento:
{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://ollama-host:11434/v1",
        api: "openai-completions",
        injectNumCtxForOpenAICompat: false,
        apiKey: "ollama-local",
        models: [...]
      }
    }
  }
}
Para modelos descubiertos automáticamente, OpenClaw usa la ventana de contexto informada por Ollama cuando está disponible, incluidos valores PARAMETER num_ctx mayores de Modelfiles personalizados. De lo contrario, vuelve a la ventana de contexto predeterminada de Ollama usada por OpenClaw.Puedes establecer valores predeterminados de contextWindow, contextTokens y maxTokens a nivel de proveedor para cada modelo bajo ese proveedor de Ollama, y luego sobrescribirlos por modelo cuando sea necesario. contextWindow es el presupuesto de prompt y Compaction de OpenClaw. Las solicitudes nativas de Ollama dejan options.num_ctx sin configurar a menos que configures explícitamente params.num_ctx, para que Ollama pueda aplicar su propio valor predeterminado basado en el modelo, OLLAMA_CONTEXT_LENGTH o VRAM. Para limitar o forzar el contexto de ejecución por solicitud de Ollama sin reconstruir un Modelfile, configura params.num_ctx; los valores no válidos, cero, negativos y no finitos se ignoran. El adaptador compatible con OpenAI para Ollama sigue inyectando options.num_ctx de forma predeterminada desde el params.num_ctx o contextWindow configurado; desactívalo con injectNumCtxForOpenAICompat: false si tu upstream rechaza options.Las entradas de modelos nativos de Ollama también aceptan las opciones comunes 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 claves de solicitud de Ollama, por lo que los params de ejecución de OpenClaw como streaming no se filtran a Ollama. Usa params.think o params.thinking para enviar think de nivel superior de Ollama; false desactiva el pensamiento a nivel de API para modelos de pensamiento de 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,
            },
          }
        ]
      }
    }
  }
}
agents.defaults.models["ollama/<model>"].params.num_ctx por modelo también funciona. Si ambos están configurados, la entrada explícita de modelo del proveedor gana sobre el valor predeterminado del agente.
Para modelos nativos de Ollama, OpenClaw reenvía el control de pensamiento como Ollama lo 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 sin pensamiento exponen solo /think off.
openclaw agent --model ollama/gemma4 --thinking off
openclaw agent --model ollama/gemma4 --thinking low
También puedes establecer un valor predeterminado de modelo:
{
  agents: {
    defaults: {
      models: {
        "ollama/gemma4": {
          thinking: "low",
        },
      },
    },
  },
}
params.think o params.thinking por modelo puede desactivar o forzar el pensamiento de la API de Ollama para un modelo configurado específico. OpenClaw conserva esos params explícitos del modelo cuando la ejecución activa solo tiene el valor predeterminado implícito off; los comandos de ejecución no off como /think medium siguen sobrescribiendo la ejecución activa.
OpenClaw trata los modelos con nombres como deepseek-r1, reasoning o think como capaces de razonamiento de forma predeterminada.
ollama pull deepseek-r1:32b
No se necesita configuración adicional. OpenClaw los marca automáticamente.
Ollama es gratuito y se ejecuta localmente, por lo que todos los costos de modelos se establecen en $0. Esto se aplica tanto a los modelos descubiertos automáticamente como a los definidos manualmente.
El Plugin de Ollama incluido registra un proveedor de embeddings de memoria para búsqueda de memoria. Usa la URL base de Ollama configurada y la clave de API, llama al endpoint actual /api/embed de Ollama y agrupa varios fragmentos de memoria en una solicitud input cuando es posible.
PropiedadValor
Modelo predeterminadonomic-embed-text
Auto-pullSí — el modelo de embeddings se descarga automáticamente si no está presente localmente
Los embeddings en tiempo de consulta usan prefijos de recuperación para modelos que los requieren o recomiendan, incluidos 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 embeddings de 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 embeddings remoto, mantén 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,
        },
      },
    },
  },
}
La integración de Ollama de OpenClaw usa la API nativa de Ollama (/api/chat) de forma predeterminada, lo que admite por completo streaming y llamadas a herramientas simultáneamente. No se necesita ninguna configuración especial.Para solicitudes nativas de /api/chat, OpenClaw también reenvía el control de razonamiento directamente a Ollama: /think off y openclaw agent --thinking off envían think: false en el nivel superior, salvo 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".
Si necesitas usar el endpoint compatible con OpenAI, consulta la sección “Modo compatible con OpenAI heredado” anterior. Es posible que streaming y las llamadas a herramientas no funcionen simultáneamente en ese modo.

​
Solución de problemas

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 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 VM de WSL2, systemd vuelve a iniciar Ollama y el bucle se repite.Evidencia común:
  • reinicios o terminaciones repetidos de WSL2 desde el lado de Windows
  • CPU alta en app.slice o ollama.service poco después del inicio de WSL2
  • SIGTERM de systemd en lugar de un evento del 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:
sudo systemctl disable ollama
Añade esto a %USERPROFILE%\.wslconfig en el lado de Windows y luego ejecuta wsl --shutdown:
[experimental]
autoMemoryReclaim=disabled
Define un keep-alive más corto en el entorno del servicio Ollama, o inicia Ollama manualmente solo cuando lo necesites:
export OLLAMA_KEEP_ALIVE=5m
ollama serve
Consulta ollama/ollama#11317.
Asegúrate de que Ollama esté en ejecución, de que hayas definido OLLAMA_API_KEY (o un perfil de autenticación) y de que no hayas definido una entrada explícita models.providers.ollama:
ollama serve
Verifica que se pueda acceder a la API:
curl http://localhost:11434/api/tags
Si tu modelo no aparece en la lista, descarga el modelo localmente o defínelo explícitamente en models.providers.ollama.
ollama list  # See what's installed
ollama pull gemma4
ollama pull gpt-oss:20b
ollama pull llama3.3     # Or another model
Comprueba que Ollama se esté ejecutando en el puerto correcto:
# Check if Ollama is running
ps aux | grep ollama

# Or restart Ollama
ollama serve
Verifica desde la misma máquina y runtime que 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 usa /v1, lo que selecciona el comportamiento compatible con OpenAI en lugar de Ollama nativo.
  • El host remoto necesita cambios de firewall o de vinculación de LAN en el lado de Ollama.
  • El modelo está presente en el daemon de tu portátil, pero no en el daemon remoto.
Esto normalmente significa que el proveedor está usando el modo compatible con OpenAI o que el modelo no puede manejar esquemas de herramientas.Prefiere el modo nativo de Ollama:
{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://ollama-host:11434",
        api: "ollama",
      },
    },
  },
}
Si un modelo local pequeño sigue fallando con esquemas de herramientas, define compat.supportsTools: false en esa entrada de modelo y vuelve a probar.
Las respuestas alojadas de Kimi/GLM que son largas secuencias de símbolos no lingüísticos se tratan como salida fallida del proveedor en lugar de una respuesta correcta del asistente. Eso permite que el reintento normal, la reserva o el manejo de errores tomen el control sin persistir el texto dañado en la sesión.Si ocurre repetidamente, captura el nombre de modelo sin procesar, el archivo de sesión actual y si la ejecución usó Cloud + Local o Cloud only; luego prueba una sesión nueva y un modelo de reserva:
openclaw infer model run --model ollama/kimi-k2.5:cloud --prompt "Reply with exactly: ok" --json
openclaw models set ollama/gemma4
Los modelos locales grandes pueden necesitar una primera carga larga antes de que comience el streaming. Mantén el tiempo de espera limitado al proveedor Ollama y, opcionalmente, pide 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 propio host tarda en aceptar conexiones, timeoutSeconds también amplía el tiempo de espera de conexión protegido de Undici para este proveedor.
Muchos modelos de Ollama anuncian contextos más grandes de lo que tu hardware puede ejecutar cómodamente. Ollama nativo usa el contexto de runtime predeterminado de Ollama, salvo que definas params.num_ctx. Limita tanto el presupuesto de OpenClaw como el contexto de solicitud de Ollama cuando quieras 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 },
          },
        ],
      },
    },
  },
}
Reduce primero contextWindow si OpenClaw está enviando demasiado prompt. Reduce params.num_ctx si Ollama está cargando un contexto de runtime demasiado grande para la máquina. Reduce maxTokens si la generación tarda demasiado.
Más ayuda: Solución de problemas y FAQ.

​
Relacionado

Proveedores de modelos

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

Selección de modelos

Cómo elegir y configurar modelos.

Búsqueda web de Ollama

Configuración completa y detalles de comportamiento para la búsqueda web impulsada por Ollama.

Configuración

Referencia completa de configuración.