Skip to content

Modelos locales: Ollama, vLLM y ds4 ​

Hasta la lección anterior, OpenClaw solo usaba APIs en la nube. En esta lección cambiamos de enfoque: OpenClaw modelos locales — la inferencia se ejecuta en tu propio hardware, sin gastar en API y sin que ni un solo byte de tus conversaciones salga de casa. En la arquitectura oficial, tanto los modelos como el harness del agente (Claude, Codex, modelos locales) son plugins intercambiables, y los backends locales son ciudadanos de primera clase completos: Ollama, vLLM y SGLang son providers integrados, LM Studio tiene una guía dedicada, y ds4 (ejecuta DeepSeek V4 Flash localmente en macOS Metal) se conecta solo con configuración. Todo el proceso toma unos 10 minutos; este tutorial se basa en la v2026.10.9.

Qué podrás hacer al terminar ​

  • Conectar modelos locales a OpenClaw con Ollama, con las llamadas a herramientas funcionando — Claw puede trabajar de verdad, no solo conversar
  • Autoalojar pesos de código abierto en servidores GPU con vLLM / SGLang, OpenClaw detectando automáticamente el directorio de modelos
  • Ejecutar DeepSeek V4 Flash localmente en macOS con ds4, configurando los niveles de thinking y el inicio bajo demanda
  • Distinguir, con la tabla oficial de selección, qué escenario cubre cada uno de los siete backends locales, para no perderte ni en la primera instalación
  • Usar comandos de diagnóstico por niveles para diferenciar entre «el modelo responde» y «el Gateway enruta correctamente», y configurar un esquema híbrido de prioridad local + respaldo en la nube

🎒 Preparativos antes de empezar ​

  • Haber completado Descripción general de conexión de modelos: sistema de providers y cambio de modelo: tener claras las reglas de referencia de provider/model y los tres pasos de «instalar plugin → configurar credenciales → elegir modelo»
  • OpenClaw instalado y con el Gateway en ejecución: openclaw gateway status produce salida
  • Tener una máquina capaz de ejecutar modelos — incluso la versión mínima de la receta oficial alojada de llama.cpp requiere 8 GiB de memoria del host como punto de partida (receta de contexto de 64K); las necesidades reales dependen de los pesos del modelo, el contexto y el entorno de ejecución
  • Tener instalado al menos un backend de inferencia local (a elegir entre Ollama / vLLM / SGLang / LM Studio / ds4), o instalarlo sobre la marcha siguiendo los pasos de abajo

💡 ¿Por qué usar modelos locales?

Tres razones contundentes: gratuito — la inferencia ocurre en tu CPU/GPU, sin facturas por token; sin conexión — una vez descargado, el modelo funciona incluso sin internet, ideal para redes internas y entornos confidenciales; privacidad — las conversaciones, la memoria y los archivos nunca salen de tu hardware. El costo también es claro: la calidad y la velocidad están limitadas por el hardware, y los modelos locales no tienen los filtros de seguridad del proveedor de alojamiento, así que debes ajustar tú mismo los permisos de las herramientas (se detalla en el paso 1).

Hazlo conmigo ​

Paso 1: elige el backend — ubícate en la tabla oficial de selección ​

Por qué: cada backend local tiene su función, y elegir mal hace que todo cueste el doble. La guía oficial de local-models ofrece una tabla de selección; ubícate primero en ella:

BackendCuándo usarloCómo conectarse
OllamaFlujos de trabajo CLI, biblioteca de modelos rica, servicio systemd sin mantenimientoProvider integrado (paso 2)
vLLM / SGLang / MLXAutoalojamiento de alto rendimiento, endpoint HTTP compatible con OpenAIvLLM y SGLang como providers integrados (paso 3)
ds4Ejecuta DeepSeek V4 Flash localmente en macOS Metal, con llamadas a herramientas compatibles con OpenAISolo configuración (paso 4)
LM StudioPrimer despliegue local, cargador con GUI, API Responses nativaGuía de onboarding (paso 4)
llama.cpp (plugin)Selección de modelo según hardware, verificación de descargas, OpenClaw server gestionadoTras instalar el plugin de llama.cpp openclaw onboard elige Managed local server
llmmanDescarga de modelos desde repositorios OCI + motores llama.cpp/vLLM/MLX + enrutamiento híbrido local/gestionadoprovider independiente
LiteLLM / proxy personalizado compatible con OpenAIInterponer una capa delante de otras API de modelosla lección anterior mediante el flujo custom

Tres reglas generales que se usarán en cada paso posterior:

  1. Adaptador: cuando un provider personalizado define baseUrl pero omite api, el valor por defecto es openai-completions; si el backend es compatible con la API Responses se puede usar api: "openai-responses" (LM Studio lo admite). Ollama es un caso especial: usa el adaptador nativo (api: "ollama"), ver la advertencia sobre /v1 en el paso 2.
  2. Requisitos de hardware: la necesidad de memoria depende de los pesos del modelo, el contexto, el runtime y otras cargas en la máquina; la receta oficial gestionada de llama.cpp usa un contexto de 64K y la más pequeña parte de 8 GiB de memoria del host como mínimo, y no se garantiza que funcione, y mucho menos que sea rápida. Deja margen suficiente para el prompt completo, los esquemas de herramientas, el historial y la salida de OpenClaw.
  3. Seguridad: los modelos locales no ofrecen los filtros de seguridad de un proveedor gestionado. Los permisos de herramientas y las defensas contra inyección de prompts deben ajustarse según la capacidad del modelo: cuanto más débil sea el modelo, más fácilmente puede ser desviado por instrucciones inyectadas en páginas web o archivos.

Paso 2: conectar Ollama (punto de partida recomendado para modelos locales) ​

Por qué: Ollama es el camino más cómodo para modelos locales: OpenClaw provider integrado, Ollama descarga modelos con un solo comando y, una vez instalado, funciona como un servicio en segundo plano sin mantenimiento.

Método A (recomendado): guía de onboarding ​

Primero instala Ollama (ollama.com/download) y descarga un modelo:

bash
ollama pull gemma4

Luego ejecuta la guía:

bash
openclaw onboard

Elige Ollama y después selecciona el modo: Cloud + Local (modelos locales + modelos en la nube de :cloud al iniciar sesión) o Local only (solo local).

Deberías ver: la guía comprueba primero el host de Ollama por defecto o configurado; el descubrimiento automático solo reconoce los modelos ya cargados en memoria (informados por /api/ps) y exige soporte de herramientas + al menos 16K de contexto (confirmado por /api/show). La ruta elegida debe pasar una completion real antes de guardarse: el proceso de descubrimiento nunca descarga ni carga automáticamente modelos inactivos. Los modelos instalados pero no cargados no se descubren automáticamente: en la versión de escritorio, en Model Setup, usa la tarjeta de Ollama con Choose connection → Local only para preparar un modelo inactivo ya instalado que pase la comprobación de vida, sin necesidad de cargarlo manualmente primero. Al terminar, openclaw models list --provider ollama lista los modelos.

Versión no interactiva (ambos parámetros personalizados pueden omitirse):

bash
openclaw onboard --non-interactive --accept-risk --skip-health \
  --auth-choice ollama \
  --custom-base-url "http://ollama-host:11434" \
  --custom-model-id "qwen3.5:27b"

Si se omite la base URL se usa el host local por defecto; si se omite el ID del modelo, se prioriza un modelo ya instalado, con soporte de herramientas y con contexto ≥ 16K (con preferencia por modelos no razonadores y, en segundo lugar, por modelos pequeños); si ninguno califica, se prueba el recomendado gemma4.

Método B: configuración manual ​

bash
export OLLAMA_API_KEY="ollama-local"   # 本地/LAN 主机任意值即可
openclaw models set ollama/gemma4

O escríbelo en el archivo de configuración:

json5
{
  agents: {
    defaults: {
      model: { primary: "ollama/gemma4" },
    },
  },
}

⚠️ El baseUrl de Ollama no debe llevar /v1 (al contrario que otros backends)

OpenClaw usa con Ollama la API nativa /api/chat, no la /v1 compatible con OpenAI. Hay que escribir la dirección nativa baseUrl: "http://host:11434": si incluye /v1 se rompe la llamada a herramientas y el modelo escupe el JSON de tool-call como texto plano. vLLM, SGLang, ds4 y LM Studio son justo lo contrario: sus baseUrl deben llevar /v1.

Reglas de credenciales: las direcciones de Ollama en loopback, redes privadas, .local o nombres de host desnudos no necesitan un token real; OpenClaw usa el marcador ollama-local; solo los hosts remotos en internet público y https://ollama.com requieren un OLLAMA_API_KEY real o un auth profile.

Ollama Cloud (opcional): el ecosistema de Ollama sin ocupar hardware local ​

¿No quieres ejecutar modelos localmente pero sí usar los modelos gestionados del ecosistema de Ollama? El provider independiente ollama-cloud se conecta directamente a https://ollama.com sin necesidad de un daemon local:

bash
openclaw onboard --auth-choice ollama-cloud

El modelo por defecto del onboarding es ollama-cloud/minimax-m2.7; el catálogo gestionado incluye IDs como deepseek-v4-pro, glm-5.2, kimi-k3, minimax-m3, gpt-oss:20b, entre otros. En modo híbrido, ejecuta ollama signin en el host local para usar simultáneamente modelos locales y modelos en la nube :cloud a través del mismo host de Ollama (por ejemplo minimax-m2.7:cloud, kimi-k3:cloud).

  • openclaw models list --provider ollama lista tus modelos locales

Paso 3: conectar vLLM o SGLang (autoalojamiento en GPU de alto rendimiento) ​

Por qué: si tienes un servidor con GPU o una máquina con mucha VRAM y quieres autoalojar pesos abiertos con alto rendimiento (los pesos abiertos de LongCat de la lección anterior son de este tipo de uso), vLLM y SGLang son ambos providers integrados, compatibles con OpenAI vía /v1, con descubrimiento automático de modelos.

Con vLLM funciona en cuatro pasos. Primero memoriza cuatro propiedades: id de provider vllm, API openai-completions, autenticación VLLM_API_KEY, baseUrl por defecto http://127.0.0.1:8000/v1.

bash
vllm serve <model-id>              # 1. 起服务,模型 ID 换成你要托管的
export VLLM_API_KEY="vllm-local"   # 2. 服务器不鉴权时任非空值,作为启用发现的 opt-in 信号
json5
// 3. 选模型
{
  agents: {
    defaults: {
      model: { primary: "vllm/your-model-id" },
    },
  },
}
bash
openclaw models list --provider vllm   # 4. 验证

Deberías ver: models list lista los modelos de vLLM; si se define VLLM_API_KEY y no se escribe models.providers.vllm, OpenClaw consulta GET http://127.0.0.1:8000/v1/models y genera automáticamente las entradas de modelos, e incluso reconoce los modelos razonadores de las series DeepSeek V4 y Nemotron 3 (incluidos alias como yk_deepseek_v4). Ojo: en cuanto escribes models.providers.vllm, solo se reconocen los modelos escritos a mano; para mantener el comportamiento dinámico, añade el comodín "vllm/*": {} en agents.defaults.models.

Un solo comando no interactivo (para despliegues en CI / scripts):

bash
openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice vllm \
  --custom-base-url "http://127.0.0.1:8000/v1" \
  --custom-api-key "vllm-local" \
  --custom-model-id "your-model-id"

Cuando vLLM corre en otra máquina/puerto, quieres fijar parámetros de contexto o usar una Key real, escribe una configuración explícita (extracto literal del ejemplo oficial):

json5
{
  models: {
    providers: {
      vllm: {
        baseUrl: "http://127.0.0.1:8000/v1",
        apiKey: "${VLLM_API_KEY}",
        api: "openai-completions",
        timeoutSeconds: 300, // 可选:给慢的本地模型延长请求超时
        models: [
          {
            id: "your-model-id",
            name: "Local vLLM Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}
🔧 Avanzado (opcional): programación prioritaria de solicitudes interactivas

Cuando un mismo vLLM atiende a la vez conversaciones interactivas y tareas en segundo plano como cron / consolidación de memoria, activa primero la programación nativa por prioridad en el servidor:

bash
vllm serve <model-id> --scheduling-policy priority

Luego activa el opt-in para el modelo correspondiente:

json5
{
  agents: {
    defaults: {
      models: {
        "vllm/your-model-id": { params: { priorityScheduling: true } },
      },
    },
  },
}

Mapeo de prioridades: los turnos interactivos y el /compact manual van a -100, el trabajo delegado o sin clasificar a 0, y cron / latidos / memoria / completados auxiliares simples a 100: los números menores se programan primero y, en caso de contención, se desempata por orden de llegada. El interruptor está desactivado por defecto y solo afecta a los modelos vllm/* seleccionados.

Con SGLang es el mismo procedimiento (integrado y activado por defecto, baseUrl por defecto http://127.0.0.1:30000/v1):

bash
export SGLANG_API_KEY="sglang-local"   # 服务器不鉴权时任非空值
openclaw onboard --auth-choice sglang

El modelo por defecto del placeholder en el onboarding es sglang/Qwen/Qwen3-8B. Si se define SGLANG_API_KEY y no se escribe models.providers.sglang, el descubrimiento automático funciona igual; para fijar los parámetros escribe una configuración explícita, con la misma forma que vLLM (vllm se cambia por sglang, y el puerto por 30000).

💡 MLX u otros servicios locales compatibles con OpenAI también se pueden conectar

Cualquier servicio local que exponga un /v1/chat/completions de estilo OpenAI está dentro del alcance: MLX (mlx_lm.server), LiteLLM, OAI-proxy, etc. Sigue el flujo custom de la lección anterior, con --custom-provider-id dale un id local (por ejemplo mlx). Escribe el id del modelo con la key interna original del provider (por ejemplo mlx-community/Qwen3-30B-A3B-6bit), y al referenciarlo añade el prefijo: mlx/mlx-community/Qwen3-30B-A3B-6bit.

  • openclaw models list --provider vllm (o --provider sglang) lista los modelos alojados

Paso 4: conectar ds4 o LM Studio (DeepSeek en macOS y GUI para principiantes) ​

Por qué: dos backends distintivos cubren otras dos clases de necesidades: ds4 da a los usuarios de Mac una vía para ejecutar DeepSeek V4 Flash localmente; LM Studio da una GUI a quienes no quieren tocar la línea de comandos.

ds4: DeepSeek V4 Flash local en macOS Metal ​

Primero dejemos claro qué es ds4: un proyecto local de antirez (github.com/antirez/ds4), que ejecuta DeepSeek V4 Flash GGUF en el backend Metal de macOS y expone un /v1 compatible con OpenAI. No es un servicio en la nube ni un producto oficial de DeepSeek; en el lado de OpenClaw no hay plugin, la conexión es puramente por configuración.

Levanta el servicio (<DS4_DIR> se reemplaza por la ruta de tu checkout de ds4):

bash
<DS4_DIR>/ds4-server \
  --model <DS4_DIR>/ds4flash.gguf \
  --host 127.0.0.1 \
  --port 18000 \
  --ctx 32768 \
  --tokens 128

Deberías ver: la respuesta de curl http://127.0.0.1:18000/v1/models incluye deepseek-v4-flash.

Luego escribe la configuración de OpenClaw (extracto de la configuración oficial completa):

json5
{
  agents: {
    defaults: {
      model: { primary: "ds4/deepseek-v4-flash" },
      models: { "ds4/deepseek-v4-flash": { alias: "DS4 local" } },
    },
  },
  models: {
    mode: "merge",
    providers: {
      ds4: {
        baseUrl: "http://127.0.0.1:18000/v1",
        apiKey: "ds4-local",
        api: "openai-completions",
        timeoutSeconds: 300,
        models: [
          {
            id: "deepseek-v4-flash",
            name: "DeepSeek V4 Flash (ds4)",
            reasoning: true,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 32768,
            maxTokens: 128,
            compat: {
              supportsUsageInStreaming: true,
              supportsReasoningEffort: true,
              maxTokensField: "max_tokens",
              supportsStrictMode: false,
              thinkingFormat: "deepseek",
              supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],
            },
          },
        ],
      },
    },
  },
}

Dos puntos clave:

  • --ctx 32768 como punto de partida: los turnos de agente de OpenClaw llevan el schema de herramientas y el contexto del workspace; con --ctx 4096 pasa la prueba directa con curl, pero un turno de agente a plena carga dará 500 prompt exceeds context. contextWindow se alinea con --ctx, y maxTokens se alinea con --tokens.
  • Think Max requiere un contexto grande: solo se activa con ds4-server --ctx 393216 y solicitando reasoning_effort: "max"; en ese caso los metadatos del modelo se sincronizan cambiando a contextWindow: 393216, maxTokens: 384000, y añadiendo supportedReasoningEfforts con "max".
🔧 Inicio bajo demanda: haz que OpenClaw solo levante ds4 cuando se use

¿No quieres que ds4 resida permanentemente consumiendo memoria? Añade localService en la misma entrada de provider; OpenClaw iniciará el servicio automáticamente al seleccionar un modelo ds4/... (ejemplo oficial tal cual):

json5
{
  models: {
    providers: {
      ds4: {
        baseUrl: "http://127.0.0.1:18000/v1",
        apiKey: "ds4-local",
        api: "openai-completions",
        timeoutSeconds: 300,
        localService: {
          command: "<DS4_DIR>/ds4-server",
          args: [
            "--model",
            "<DS4_DIR>/ds4flash.gguf",
            "--host",
            "127.0.0.1",
            "--port",
            "18000",
            "--ctx",
            "32768",
            "--tokens",
            "128",
          ],
          cwd: "<DS4_DIR>",
          healthUrl: "http://127.0.0.1:18000/v1/models",
          readyTimeoutMs: 300000,
          idleStopMs: 0,
        },
        models: [
          {
            id: "deepseek-v4-flash",
            name: "DeepSeek V4 Flash (ds4)",
            reasoning: true,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 32768,
            maxTokens: 128,
            compat: {
              supportsUsageInStreaming: true,
              supportsReasoningEffort: true,
              maxTokensField: "max_tokens",
              supportsStrictMode: false,
              thinkingFormat: "deepseek",
              supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],
            },
          },
        ],
      },
    },
  },
}

No te equivoques con los tres campos: command debe ser una ruta ejecutable absoluta (sin búsqueda en shell ni expansión de ~); readyTimeoutMs: 300000 dale suficientes 5 minutos: ds4 tiene una fase fría de residencia en Metal y de precalentamiento del modelo, la primera petición es lenta de todos modos; healthUrl usa /v1/models para comprobar que está vivo.

LM Studio: cargador con GUI, onboarding totalmente automático ​

LM Studio usa una GUI para ejecutar modelos llama.cpp (GGUF) o MLX, y también tiene un daemon headless llmster. Tras instalarlo, tres pasos:

bash
lms server start --port 1234        # 1. 起本地服务(headless 版用 lms daemon up)
export LM_API_TOKEN="your-lm-studio-api-token"   # 2. LM Studio 开了认证才需要,没开就留空
openclaw onboard                    # 3. 选 LM Studio,在 Default model 提示里挑模型

Deberías ver: el onboarding primero consulta el /api/v1/models del host de LM Studio; solo los modelos que LM Studio reporte como «con entrenamiento de herramientas + al menos 16K de contexto efectivo» se recomiendan automáticamente (los modelos ya cargados se calculan según el contexto de la instancia cargada, no según el máximo anunciado); tras seleccionarlo se pasa una completion real antes de guardar, y la comprobación automática jamás descarga modelos por ti.

La key de los modelos de LM Studio tiene el formato author/model-name (por ejemplo qwen/qwen3.5-9b); en OpenClaw la referencia añade el prefijo del provider: lmstudio/qwen/qwen3.5-9b. Para consultar la key exacta, cambiar el valor por defecto o refrescar tras instalar nuevos modelos:

bash
curl http://localhost:1234/api/v1/models              # 看返回里的 key 字段
openclaw models set lmstudio/qwen/qwen3.5-9b
openclaw models list --provider lmstudio --refresh    # 装了新模型后刷新目录

En el modo merge por defecto, --refresh añade los modelos descubiertos y conserva los metadatos de tus entradas escritas a mano (nombre, límite de contexto, etc.). Versión no interactiva: openclaw onboard --non-interactive --accept-risk --skip-health --auth-choice lmstudio; para dar explícitamente todos los parámetros añade además --custom-base-url http://localhost:1234/v1 --lmstudio-api-key "$LM_API_TOKEN" --custom-model-id qwen/qwen3.5-9b.

  • openclaw models list --provider ds4 (o --provider lmstudio) te permite ver tus modelos

Paso 5: validar la cadena y configurar el fallback híbrido ​

Por qué: configuración guardada en disco ≠ que el agente pueda trabajar. «El modelo responde», «el Gateway enruta con normalidad» y «las herramientas se ejecutan de verdad» son tres capas, y la documentación oficial da comandos de diagnóstico por capas: sabiendo qué capa se rompió, sabes dónde reparar.

bash
# 第一层:模型本身能不能回话(不带工具、不带 agent 上下文)
openclaw infer model run --local --model <provider/model> --prompt "Reply with exactly: pong" --json

# 第二层:Gateway 路由通不通(只发 prompt,跳过 transcript、工具与内置 MCP,
# 但仍走完整的 Gateway 路由、auth 与 provider 选择)
openclaw infer model run --gateway --model <provider/model> --prompt "Reply with exactly: pong" --json

Tercera capa: prueba de humo de herramientas, ejecuta un turno completo de agente (tomando ds4 como ejemplo):

bash
openclaw agent \
  --local \
  --session-id ds4-tool-smoke \
  --model ds4/deepseek-v4-flash \
  --thinking off \
  --message "Use the shell command pwd once, then reply exactly: tool-ok <output>" \
  --json \
  --timeout 240

Deberías ver: executionTrace.winnerProvider es ds4, executionTrace.winnerModel es deepseek-v4-flash, toolSummary.calls es al menos 1, y la respuesta visible empieza con tool-ok: la herramienta se ejecutó de verdad, no es que el modelo te recite el JSON.

Cuando todo pase, establece el modelo que te resulte cómodo como valor por defecto diario:

bash
openclaw models set <provider/model>

Si quieres ahorrar dinero sin interrumpir el servicio, configura además una capa de fallback híbrido, el enfoque recomendado por la guía oficial de local-models: prioridad local, fallback en la nube; cuando un provider falla, se cae turno a turno al siguiente fallback (el ejemplo oficial surge de invertir el orden primary/fallbacks):

json5
{
  agents: {
    defaults: {
      model: {
        primary: "lmstudio/my-local-model",   // 本地优先
        fallbacks: ["anthropic/claude-sonnet-4-6", "anthropic/claude-opus-4-6"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "lmstudio/my-local-model": { alias: "Local" },
        "anthropic/claude-opus-4-6": { alias: "Opus" },
      },
    },
  },
  models: {
    mode: "merge",   // merge 保住云端模型目录,随时 /model 切换
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

Para prioridad en la nube con fallback local, invierte primary/fallbacks, conservando el bloque providers y models.mode: "merge" tal cual. Ten en cuenta que el fallback es un cambio por turno que «solo se activa al fallar»; si quieres un enrutamiento por petición que deje en local las peticiones pequeñas y suba a la nube solo las muy grandes, la documentación oficial señala el Hybrid inference de llmman.

  • Las tres capas de validación pasan: dos niveles de pong + prueba de humo de herramientas toolSummary.calls ≥ 1

Punto de control ✅ ​

  • Elegiste el backend correcto según la tabla oficial de selección: Ollama (CLI) / vLLM, SGLang (alto rendimiento en GPU) / ds4 (DeepSeek en macOS) / LM Studio (GUI)
  • openclaw models list --provider <id> puede listar tus modelos locales
  • El baseUrl de Ollama es http://host:11434 (sin /v1); vLLM / SGLang / ds4 / LM Studio llevan /v1
  • openclaw infer model run --local y --gateway devuelven pong
  • En la prueba de humo del agente, toolSummary.calls ≥ 1: la llamada a herramientas se ejecuta de verdad, no es texto JSON escupido
  • Quieres ahorrar dinero sin interrumpir el servicio: configuraste el esquema híbrido con fallbacks, y models.mode: "merge" conserva el catálogo de modelos en la nube

Avisos de errores comunes ​

❌ El baseUrl de Ollama lleva /v1——las llamadas a herramientas se rompen por completo ​

Ollama usa el adaptador nativo /api/chat, y el baseUrl debe ser http://host:11434 (sin /v1). Si lleva /v1 pasa al modo compatible con OpenAI, y las llamadas a herramientas se rompen: el modelo escupe el JSON de tool-call como texto plano. Es justo lo contrario de vLLM / SGLang / ds4 / LM Studio (todos requieren /v1)——si no lo recuerdas, recuerda que «Ollama va por su cuenta».

❌ ds4 --ctx 4096: curl funciona, pero el turno del agent da 500 ​

La causa de 500 prompt exceeds context: el turno del agent de OpenClaw incluye el esquema de herramientas y el contexto del workspace, mucho más grande que un mensaje de prueba con curl. Usa ds4-server --ctx con al menos 32768 y alinea models.providers.ds4.models[].contextWindow. Para Think Max, arranca directamente con --ctx 393216.

❌ El modelo local «puede responder», pero las llamadas a herramientas aparecen como texto JSON/XML en bruto ​

Primero haz el diagnóstico por capas del paso 5. Si los dos niveles de infer model run funcionan pero el turno completo se desordena, revisa en este orden:

  1. Los modelos locales de Ollama, LM Studio y los servicios locales alojados activan automáticamente la Tool Search estructurada cuando tools.toolSearch no está configurado (aplaza el envío del esquema y conserva la capacidad)——no la desactives.
  2. Los usuarios de vLLM deben confirmar primero que el arranque incluye el parser de tool-call y la chat template correctos (documentación oficial de vLLM: Qwen2.5 usa hermes, Qwen3-Coder usa qwen3_xml).
  3. Si sigue fallando, en la entrada del modelo dedicado puedes añadir params.extra_body.tool_choice: "required" para forzar las llamadas a herramientas——solo para modelos que «deberían llamar herramientas en cada turno», no lo pongas como valor global por defecto.
  4. Último recurso: desactiva las herramientas en ese modelo con compat.supportsTools: false; o activa el modo ligero agents.defaults.experimental.localModelLean: true (elimina herramientas con esquemas grandes como browser, automations, message, image_generate, music_generate, video_generate, tts, pdf).

❌ Modelos lentos / fríos que agotan el tiempo de espera ​

Es habitual que un modelo local grande tarde en el primer token, que LM Studio haga carga en frío o que ds4 tenga precalentamiento en frío. Configura timeoutSeconds en la entrada del provider (por ejemplo 300)——cubre conexión, cabeceras de respuesta, body en streaming y aborto total, y tiene prioridad sobre el ajuste global agents.defaults.timeoutSeconds. Para el arranque en frío de ds4 configura además localService.readyTimeoutMs: 300000.

❌ WSL2 + Ollama + NVIDIA/CUDA: la máquina virtual se reinicia una y otra vez ​

El instalador oficial de Ollama para Linux activa el servicio systemd con Restart=always. En entornos WSL2 con GPU, el autoarrance al encender recarga el último modelo y bloquea la memoria del host, arrastrando la VM de WSL2 a un bucle de reinicios (la página oficial de resolución de problemas lo lista como WSL2 crash loop). En WSL2 no dejes que Ollama cargue modelos automáticamente al arrancar.

❌ Error de cálculo del presupuesto de contexto: salida truncada, a punto del límite queda un solo token ​

OpenClaw hace una comprobación previa según la ventana del modelo: avisa si el margen baja del 20% (mínimo 8k) y bloquea de forma estricta si baja del 10% (mínimo 4k). Los modelos locales de Ollama conectados por descubrimiento tienen por defecto un límite de salida de 8,192 token (OpenClaw envía el límite de salida como num_predict al Ollama nativo); para recuperar el comportamiento ilimitado por defecto de Ollama, configura params: { num_predict: -1 }. En las entradas de modelos personalizadas, escribe valores reales en contextWindow/maxTokens en lugar de heredar el valor de reserva por defecto de 200000.

❌ Tras ejecutar el Gateway como demonio, las Key exportadas «no surten efecto» ​

Un error clásico que conviene repetir: los servicios de launchd / systemd no ven las variables de entorno del shell interactivo. Escribe OLLAMA_API_KEY, VLLM_API_KEY, SGLANG_API_KEY, LM_API_TOKEN en ~/.openclaw/.env, o proporciónaselos a ese proceso mediante env.shellEnv en la configuración.

❌ Tratar el modelo local como un «sustituto gratuito de la nube» y dejar la seguridad al descubierto ​

Los modelos locales no tienen los filtros de seguridad del proveedor alojado, y cuanto más débil es el modelo, más fácil es desviarlo con instrucciones inyectadas desde páginas web o archivos. Restringe los permisos de herramientas, mantén activada la compaction y considera un sandbox para las sesiones de chat en grupo——palabras textuales de la guía oficial de local-models: keep tool permissions and prompt-injection defenses appropriate for the model and task. Para las técnicas de endurecimiento, consulta Endurecimiento de seguridad (1): control de acceso e identidad.

Siguiente paso ​

Aquí termina el capítulo de inicio rápido: la instalación y la conexión de modelos (el paquete completo de modelos nacionales + relay + modelos locales) ya funcionan. A continuación:

Tutoriales relacionados ​

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.