Ollama

Los hosts Ollama locales y de LAN no necesitan un token portador real. OpenClaw usa el marcador local ollama-local solo para URLs base de Ollama de loopback, red privada, .local y nombres de host sin dominio.

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. Para uso alojado directo, prefiere el proveedor ollama-cloud.

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 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. Coloca la configuración de endpoint (baseUrl, api, ids de modelo, encabezados, tiempos de espera) en models.providers.<id>. Los archivos antiguos de perfil de autenticación planos, como { "ollama-windows": { "apiKey": "ollama-local" } }, no son un formato de runtime; ejecuta openclaw doctor --fix para reescribirlos al perfil de clave API canónico 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 de portador queda limitada al host donde se declaró:

• Una clave a nivel de proveedor se envía solo al host Ollama de ese proveedor.
• agents.*.memorySearch.remote.apiKey se envía solo a su host remoto de embeddings.
• 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 autohospedados.

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 serveollama pull gemma4export OLLAMA_API_KEY="ollama-local"openclaw models list --provider ollamaopenclaw models set ollama/gemma4

Esta ruta mantiene la configuración al mínimo. 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 daemon local y quieras modelos alojados de Ollama 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 daemon Ollama local o LAN haya iniciado sesión con ollama signin y deba servir tanto modelos locales como modelos :cloud.

ollama signinollama 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 proveedor personalizados cuando tengas más de un servidor Ollama. Cada proveedor obtiene su propio host, modelos, autenticación, tiempo de espera y refs 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, de modo que ollama-large/qwen3.5:27b llega 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 herramientas y contexto antes de cambiar la configuración global del runtime.

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

Usa compat.supportsTools: false solo cuando el modelo o servidor falle de forma fiable con esquemas de herramientas. Cambia capacidad del agente por estabilidad. localModelLean elimina las herramientas de navegador, cron y mensajes de la superficie directa del agente, y pone de forma predeterminada los catálogos más grandes detrás de controles estructurados de búsqueda de herramientas, excepto cuando una ejecución debe conservar la semántica de entrega directa de mensajes, pero no cambia el contexto de runtime ni el modo de pensamiento de Ollama. Combínalo con params.num_ctx explícito y params.thinking: false para modelos pequeños de pensamiento estilo Qwen que entran en bucle o gastan su presupuesto de respuesta en razonamiento oculto.

Si necesitas usar el endpoint compatible con OpenAI en su lugar (por ejemplo, detrás de un proxy que solo admite el formato de OpenAI), establece 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. Es posible que debas 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 reportada por Ollama cuando está disponible, incluidos valores PARAMETER num_ctx más grandes de Modelfiles personalizados. De lo contrario, vuelve a la ventana de contexto predeterminada de Ollama usada por OpenClaw.

Puedes establecer valores predeterminados de nivel de proveedor para contextWindow, contextTokens y maxTokens 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 establecer a menos que configures explícitamente params.num_ctx, de modo que Ollama pueda aplicar su propio valor predeterminado basado en el modelo, OLLAMA_CONTEXT_LENGTH o la VRAM. Para limitar o forzar el contexto de ejecución por solicitud de Ollama sin reconstruir un Modelfile, establece params.num_ctx; los valores no válidos, cero, negativos y no finitos se ignoran. Si actualizaste una configuración antigua que usaba solo contextWindow o maxTokens para forzar un contexto de solicitud nativa de Ollama, ejecuta openclaw doctor --fix para copiar esos presupuestos explícitos de proveedor o modelo en params.num_ctx. El adaptador de Ollama compatible con OpenAI 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 parámetros 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 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 del modelo del proveedor tiene prioridad 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 autodetectados cuya respuesta de /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 offopenclaw agent --model ollama/gemma4 --thinking low

También puedes establecer un valor predeterminado del modelo:

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

params.think o params.thinking por modelo pueden desactivar o forzar el pensamiento de la API de Ollama para un modelo configurado específico. OpenClaw conserva esos parámetros explícitos del modelo cuando la ejecución activa solo tiene el valor predeterminado implícito off; los comandos de ejecución distintos de 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 autodetectados 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.

Cuando proxy.enabled=true, las solicitudes de embeddings de memoria de Ollama al origen host-local loopback exacto derivado del baseUrl configurado usan la ruta directa protegida de OpenClaw en lugar del proxy reenviado administrado. El nombre de host configurado debe ser localhost o un literal de IP de loopback; los nombres DNS que simplemente resuelven a loopback siguen usando la ruta del proxy administrado. Los hosts Ollama de LAN, tailnet, red privada y públicos también permanecen en la ruta del proxy administrado. Las redirecciones a otro host o puerto no heredan la confianza. Los operadores aún pueden establecer la configuración global proxy.loopbackMode: "proxy" para enviar tráfico de loopback a través del proxy, o proxy.loopbackMode: "block" para denegar conexiones de loopback antes de abrir una conexión; consulta Proxy administrado para conocer el efecto en todo el proceso de esta configuración.

Los embeddings en tiempo de consulta usan prefijos de recuperación para los 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 remoto de embeddings, 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, que admite completamente streaming y llamadas a herramientas de forma simultánea. No se necesita configuración especial.

Para 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 haya un valor explícito de modelo params.think/params.thinking configurado, mientras que /think low|medium|high envía la cadena de esfuerzo think de nivel superior correspondiente. /think max se asigna al esfuerzo nativo más alto de Ollama, think: "high".

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 inicia Ollama de nuevo y el bucle se repite.

Evidencia común:

• reinicios o terminaciones repetidas de WSL2 desde el lado de Windows
• CPU alta en app.slice u 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

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

[experimental]autoMemoryReclaim=disabled

Establece un keep-alive más corto en el entorno del servicio Ollama, o inicia Ollama manualmente solo cuando lo necesites:

export OLLAMA_KEEP_ALIVE=5mollama serve

Consulta ollama/ollama#11317.

Asegúrate de que Ollama se esté ejecutando, de haber establecido 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 la API sea accesible:

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

Si tu modelo no aparece, extrae el modelo localmente o defínelo explícitamente en models.providers.ollama.

ollama list  # See what's installedollama pull gemma4ollama pull gpt-oss:20bollama pull llama3.3     # Or another model

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

# Check if Ollama is runningps aux | grep ollama # Or restart Ollamaollama serve

Verifica desde la misma máquina y ejecución que ejecuta el Gateway:

openclaw gateway status --deepcurl 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 enlace 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, establece 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, fallback o manejo de errores normal tome el control sin persistir el texto corrupto en la sesión.

Si ocurre repetidamente, captura el nombre bruto del modelo, el archivo de sesión actual y si la ejecución usó Cloud + Local o Cloud only; luego prueba con una sesión nueva y un modelo fallback:

openclaw infer model run --model ollama/kimi-k2.5:cloud --prompt "Reply with exactly: ok" --jsonopenclaw models set ollama/gemma4

Los modelos locales grandes pueden necesitar una carga inicial prolongada antes de que comience el streaming. Mantén el tiempo de espera limitado al proveedor de 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 host en sí 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 valor predeterminado de contexto del propio runtime de Ollama a menos que configures params.num_ctx. Limita tanto el presupuesto de OpenClaw como el contexto de solicitud de Ollama cuando quieras 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 },          },        ],      },    },  },}

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 se prolonga demasiado.