Ollama

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.

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.

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.

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

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.