Ollama

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.

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.

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.

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.

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.

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ñada un bloque models.providers.ollama a menos que necesite 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.

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.

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.

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.

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: [...]      }    }  }}

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.

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 offopenclaw 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.

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

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

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

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".

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=5mollama serve

Consulte ollama/ollama#11317.

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 servecurl http://localhost:11434/api/tags

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

ollama list  # Consulte qué está instaladoollama pull gemma4ollama pull gpt-oss:20bollama pull llama3.3     # O bien otro modelo

Verifíquelo 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 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.

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.

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" --jsonopenclaw models set ollama/gemma4

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.

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.