Desplegar Ollama con OpenClaw: modelos, puertos, permisos y memoria

Los fallos más habituales entre Ollama y OpenClaw no se explican solo porque «el modelo sea pequeño». Normalmente se deben a un puerto incorrecto, una URL compatible con OpenAI usada en el provider nativo, un Gateway en otro network namespace o permisos excesivos. Valida primero el provider nativo de Ollama, después el modelo en OpenClaw y, por último, memoria y automatización.

Esta guía supone localhost o una LAN privada; no expone Ollama ni el Gateway a Internet.

Elegir el modelo: conversar no equivale a trabajar como Agent

Confirma cuatro puntos:

1. Ollama descargó el modelo y puede generar.
2. El primer token y la velocidad sostenida son aceptables.
3. Funciona una tarea mínima con herramientas, no solo un saludo.
4. Hay contexto y RAM/VRAM suficientes para tareas largas.

Los modelos pequeños sirven para resumen, clasificación y flujos fijos. Para herramientas complejas, repositorios o varias rondas, prueba la tarea real antes de elegir un modelo mayor o cloud fallback.

1
2
3
4

ollama pull <model>
ollama list
curl http://127.0.0.1:11434/api/tags
curl http://127.0.0.1:11434/api/generate -d '{"model":"<model>","prompt":"Reply with exactly: ok","stream":false}'

No diagnostiques OpenClaw hasta que la segunda petición devuelva ok.

Conectar la API nativa de Ollama

No añadas /v1 a baseUrl. Una ruta compatible con OpenAI puede romper las llamadas de herramientas o hacer que el modelo emita JSON como texto.

1

export OLLAMA_API_KEY="ollama-local"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://127.0.0.1:11434",
        apiKey: "ollama-local",
        api: "ollama"
      }
    }
  },
  agents: {
    defaults: { model: { primary: "ollama/<model>" } }
  }
}

baseUrl es la clave actual; baseURL queda para ejemplos antiguos. El marcador local sirve en loopback, rangos privados, .local o nombres simples. Un host público u Ollama Cloud requiere credenciales reales.

Ejemplo con Gemma 4

No copies una etiqueta supuesta como gemma4:12b. Lee la etiqueta local exacta:

1
2
3
4
5
6

ollama list
curl http://127.0.0.1:11434/api/generate -d '{
  "model": "<your-gemma-4-tag>",
  "prompt": "Reply with exactly: ok",
  "stream": false
}'

Solo después de que funcione debes escribir esa misma etiqueta en OpenClaw. Debe coincidir exactamente con ollama list.

Confirmar que OpenClaw usa el modelo

1
2
3

openclaw models list --provider ollama
openclaw models status
openclaw infer model run --model ollama/<model> --prompt "Reply with exactly: ok"

Si /api/tags funciona pero la lista está vacía, quizá el provider esté deshabilitado, la cuenta del Gateway no herede la variable o el Gateway se ejecute en contenedor u otro host. Corrige el límite de proceso y red antes de cambiar nombres al azar.

Puertos y contenedores: cambia el significado de localhost

Ollama suele escuchar en 127.0.0.1:11434. Es lo más seguro si ambos procesos están en el mismo host, pero Docker, WSL, systemd y un Gateway remoto cambian qué significa localhost.

No publiques 11434 en todas las interfaces para hacerlo funcionar. Prefiere red privada o túnel controlado.

Restringir permisos antes de habilitar herramientas

La inferencia local no vuelve segura la ejecución de herramientas.

1. Ejecuta como usuario normal, no Administrator/root.
2. Limita el workspace a un proyecto o sandbox.
3. Exige aprobación para borrar, publicar, enviar mensajes, leer credenciales o acceder a producción.
4. No guardes secretos en prompts, memoria, logs ni Git.
5. Revisa origen y contenido de cada Skill o plugin.

Separa «puede ejecutarlo» de «puede ejecutarlo automáticamente».

Ajustar modelos locales lentos

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  models: {
    providers: {
      ollama: {
        timeoutSeconds: 300,
        models: [
          { id: "<model>", name: "<model>", params: { keep_alive: "15m" } }
        ]
      }
    }
  }
}

timeoutSeconds cubre conexión, streaming y petición completa. keep_alive reduce cold starts. Un timeout global del Agent más corto todavía puede terminar antes.

Añadir memoria solo después de validar inferencia

Orden recomendado para TencentDB Agent Memory:

1
2
3
4

1. Ollama /api/tags y una generación mínima funcionan.
2. OpenClaw models list, status e infer funcionan.
3. Activa el plugin y comprueba un hecho explícito en otra sesión.
4. Activa offload al final y verifica que node_id recupera el log original.

1
2

openclaw plugins install @tencentdb-agent-memory/memory-tencentdb
openclaw gateway restart

Si no recuerda, revisa que el plugin esté activo, el almacenamiento sea escribible y se haya creado una sesión nueva. Si offload oculta logs, comprueba el context-engine slot y el parche after-tool-call. Consulta la guía de TencentDB Agent Memory.

Mapa rápido de fallos

Resumen

Un despliegue estable empieza en la API nativa: valida 127.0.0.1:11434/api y el modelo, configura el provider sin /v1 y concede después los permisos mínimos de herramientas y memoria. Probar por separado modelo, puerto, límite de proceso y plugin es más rápido y seguro que reinstalar todo.