Ollama

Las URL de Ollama de local loopback, redes privadas, .local y nombres de host simples no necesitan un token de portador real. OpenClaw utiliza el marcador ollama-local para ellas.

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

Un proveedor personalizado con api: "ollama" sigue las mismas reglas. Por ejemplo, un proveedor ollama-remote que apunte a un host de una LAN privada 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. agents.defaults.memorySearch.provider también puede apuntar a un id de proveedor personalizado para que los embeddings utilicen ese endpoint de Ollama.

auth-profiles.json almacena la credencial de un id de proveedor; coloca 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 ejecución; openclaw doctor --fix los reescribe como un perfil canónico de clave de API ollama-windows:default y crea una copia de seguridad. Un valor baseUrl en ese archivo heredado es información irrelevante y debe trasladarse a la configuración del proveedor.

La autenticación de portador para los embeddings de memoria de Ollama se limita al host para el que se declaró:

• Una clave de proveedor se envía únicamente al host de ese proveedor.
• agents.*.memorySearch.remote.apiKey se envía únicamente a su host remoto de embeddings.
• Un valor de entorno OLLAMA_API_KEY por sí solo se considera la convención de Ollama Cloud y, de forma predeterminada, no se envía a hosts locales o autoalojados.

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

ollama serveollama pull gemma4export OLLAMA_API_KEY="ollama-local"openclaw models list --provider ollamaopenclaw models set ollama/gemma4

No añadas un bloque models.providers.ollama salvo que necesites 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. Mantenlos alineados cuando el hardware no pueda ejecutar todo el contexto anunciado por el modelo.

Sin demonio local, con 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 identificador de proveedor dedicado ollama-cloud en lugar de esta estructura, consulta Ollama Cloud.

Use identificadores 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.

Algunos modelos locales procesan 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 solo cuando el modelo o el servidor falle de forma sistemática con los esquemas de herramientas, ya que sacrifica capacidad del agente a cambio de estabilidad. localModelLean elimina las herramientas pesadas de navegador, cron, mensajería, generación multimedia, voz y PDF de la superficie directa del agente, salvo que sean necesarias 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 de razonamiento pequeños de estilo Qwen que entran en bucle o consumen su presupuesto en razonamiento oculto.

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

{  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 simultáneamente la transmisión y las llamadas a herramientas; quizá deba configurar 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 su 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: [...]      }    }  }}

Para los modelos detectados automáticamente, OpenClaw usa la ventana de contexto que informa /api/show, incluidos los valores mayores de PARAMETER num_ctx procedentes de Modelfiles personalizados; de lo contrario, recurre a la ventana de contexto predeterminada de Ollama en OpenClaw.

contextWindow, contextTokens y maxTokens en el nivel del proveedor establecen valores predeterminados para todos los modelos de ese proveedor y se pueden sobrescribir en cada modelo. contextWindow es el presupuesto propio de OpenClaw para instrucciones y Compaction. Las solicitudes nativas a /api/chat dejan options.num_ctx sin configurar, salvo que establezca params.num_ctx explícitamente, por lo que Ollama aplica el valor predeterminado de su propio modelo, de OLLAMA_CONTEXT_LENGTH o basado en la VRAM; se ignoran los valores de 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 las solicitudes nativas, 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 params.num_ctx o contextWindow configurado; desactívelo mediante injectNumCtxForOpenAICompat: false si el servicio ascendente 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 options nativas de /api/chat: 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 options anidadas. 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 configurar think en el nivel superior; false desactiva el razonamiento en el nivel de la API para los modelos de razonamiento 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,            },          }        ]      }    }  }}

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

OpenClaw reenvía el razonamiento como Ollama espera: think en el nivel superior, no options.think. Los modelos detectados automáticamente para los que /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 offopenclaw agent --model ollama/gemma4 --thinking low

También 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 tiempo de ejecución distinto de off, como /think medium, sigue prevaleciendo sobre ella. Nunca se envía una solicitud de razonamiento verdadera a un modelo marcado explícitamente con reasoning: false; una solicitud think: false se envía siempre.

Los modelos llamados deepseek-r1, reasoning, reason o think se consideran capaces de razonar de forma predeterminada, sin necesidad de configuración adicional:

ollama pull deepseek-r1:32b

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.

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 configuradas para Ollama, 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 dirigidas exactamente al origen local del host en local loopback derivado de la baseUrl configurada utilizan la ruta directa protegida de OpenClaw en lugar del proxy de reenvío administrado. El nombre de host configurado debe ser localhost o una dirección IP literal de loopback; los nombres DNS que simplemente se resuelven a loopback siguen utilizando la ruta del proxy administrado. Los hosts de Ollama en la LAN, la tailnet, redes privadas o redes públicas permanecen siempre en la ruta del proxy administrado, y las redirecciones a otro host o puerto no heredan la confianza. proxy.loopbackMode: "proxy" dirige de todos modos el tráfico de loopback a través del proxy; proxy.loopbackMode: "block" lo rechaza antes de conectarse; consulte Proxy administrado.

Los embeddings en tiempo de 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 modificar, por lo que los índices existentes no necesitan migrar de formato.

{  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, limite la autenticación a ese host:

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

Ollama utiliza de forma predeterminada la API nativa (/api/chat), que admite simultáneamente streaming y llamadas a herramientas, sin necesidad de 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 haya configurado explícitamente params.think/params.thinking; /think low|medium|high envía la cadena de esfuerzo correspondiente; /think max se asigna al nivel de esfuerzo 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 retener 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 ciclo se repite.

Indicios: reinicios o finalizaciones repetidos de WSL2, uso elevado de CPU en app.slice o ollama.service inmediatamente después de iniciar WSL2, y SIGTERM enviado por systemd en lugar del eliminador por falta de memoria 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 después ejecute wsl --shutdown:

[experimental]autoMemoryReclaim=disabled

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

export OLLAMA_KEEP_ALIVE=5mollama serve

Consulte ollama/ollama#11317.

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

ollama servecurl http://localhost:11434/api/tags

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

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

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

openclaw gateway status --deepcurl http://ollama-host:11434/api/tags

Causas habituales:

• 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 necesita cambios en el firewall o en la vinculación a la LAN.
• El modelo está en el daemon de su portátil, pero no en el remoto.

Normalmente, el proveedor está en modo compatible con OpenAI o el modelo no puede procesar esquemas de herramientas. Prefiera 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.

Las respuestas alojadas de Kimi/GLM que consisten en secuencias largas de símbolos no lingüísticos se consideran una llamada fallida al proveedor en lugar de 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 guardar texto dañado en la sesión.

Si vuelve a ocurrir, recopile el nombre del modelo, el archivo de la sesión actual y si la ejecución utilizó Cloud + Local o Cloud only; después, pruebe una sesión nueva y un modelo de respaldo:

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 mucho tiempo para la primera carga. Limite el tiempo de espera al proveedor de Ollama y, opcionalmente, 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 protegido de conexión para este proveedor.

Muchos modelos anuncian contextos mayores de los que su hardware puede ejecutar cómodamente. Ollama nativo utiliza su propio valor predeterminado de tiempo de ejecución, salvo que se establezca params.num_ctx. Limite tanto el presupuesto de OpenClaw como el contexto de la 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 tiempo de ejecución de Ollama es demasiado grande para la máquina. Reduzca maxTokens si la generación tarda demasiado.