# Cómo conectar OpenClaw a LaoZhang API

> OpenClaw puede usar LaoZhang como proveedor personalizado de Chat Completions. Necesitas acceso aprobado al servicio, una clave API del grupo adecuado y un modelo compatible; añadirlo al catálogo no basta para comprobar que tu agente lo utiliza.

- URL: https://blog.laozhang.ai/es/posts/openclaw-laozhang-ai-setup-guide
- Published: 2026-10-07
- Updated: 2026-10-07
- Author: LaoZhang AI Team (https://blog.laozhang.ai/es/about)
- Topic: Guías de API
- Tags: OpenClaw, LaoZhang API, proveedores, configuración

---
Para conectar **OpenClaw a LaoZhang API**, declara un proveedor personalizado con `baseUrl: "https://api.laozhang.ai/v1"`, usa el adaptador `openai-completions` y selecciona un modelo al que tenga acceso tu token. Una opción documentada para empezar con Chat Completions y herramientas es `gpt-5.4-mini`. Después debes comprobar que el agente y la conversación utilizan la referencia `laozhang/gpt-5.4-mini`, que recibes una respuesta real y que las herramientas autorizadas completan su ciclo.

El requisito que conviene resolver primero es el acceso: **el servicio exige aprobación en una lista de empresas admitidas**. La documentación indica registro con Gmail y facturación prepago; no permite prometer acceso inmediato o crédito gratuito a cualquier usuario. El grupo del token también condiciona los modelos disponibles. Comprueba esas condiciones antes de preparar una migración. [Requisitos de LaoZhang](https://docs.laozhang.ai/).

Esta guía parte de OpenClaw ya instalado. Describe una configuración basada en la documentación consultada el **7 de octubre de 2026**. El JSON y el cálculo de costes se han comprobado sin conexión; no hemos ejecutado OpenClaw ni realizado llamadas, pruebas de herramientas o cargos en una cuenta LaoZhang.

## Qué modelo y protocolo elegir para la primera conexión

Empieza por una combinación concreta: **LaoZhang, Chat Completions y `gpt-5.4-mini`**. El catálogo lo sitúa en el grupo predeterminado y la guía del proveedor lo incluye entre sus modelos para integrar herramientas. LaoZhang relata sus propias comprobaciones de herramientas en streaming del 5 de octubre; eso es información del proveedor, no una prueba de que tu versión y tus permisos de OpenClaw funcionen. [Catálogo](https://docs.laozhang.ai/models) y [guía de integración](https://docs.laozhang.ai/scenarios).

Elige el adaptador por el protocolo que vas a usar, no solo por el nombre del modelo:

| Ruta de LaoZhang | Formato de la petición | Decisión en OpenClaw |
| --- | --- | --- |
| `/v1/chat/completions` | `model` y `messages` | El ejemplo de esta guía usa `openai-completions`. |
| `/v1/responses` | `model` e `input` | Requiere un adaptador de Responses y soporte real del modelo y de los parámetros enviados. No basta con cambiar la URL. |
| `/v1/messages` | Protocolo Messages | Es una integración diferente; no la mezcles con el ejemplo de Chat Completions. |

La URL base termina en `/v1`; **no añadas `/chat/completions` a `baseUrl`**. El adaptador incorpora la ruta del recurso. Una base con `/v1/v1` o un recurso añadido dos veces puede producir un 404 aunque la clave sea correcta. [Protocolos y autenticación de LaoZhang](https://docs.laozhang.ai/api-manual), [proveedores personalizados de OpenClaw](https://docs.openclaw.ai/gateway/config-tools/custom-providers).

No elijas Claude a partir de un tutorial antiguo: el catálogo consultado indica que sus modelos están temporalmente fuera de servicio por falta de recursos. Tampoco interpretes los 222 modelos en línea del catálogo como 222 modelos aptos para un agente de OpenClaw: la cifra incluye otras modalidades. El acceso efectivo de tu token y la compatibilidad con herramientas son comprobaciones distintas. [Disponibilidad del catálogo](https://docs.laozhang.ai/models).

Si todavía estás decidiendo entre una API remota y un modelo local, la guía de [configuración de modelos de OpenClaw, Ollama y LM Studio](https://blog.laozhang.ai/es/posts/openclaw-llm-setup) te ayuda a elegir esa ruta. Aquí seguimos con el proveedor LaoZhang.

## Preparar la clave y añadir el proveedor

Necesitas una **API Key de LaoZhang**, no el AccessToken de la cuenta ni una clave emitida directamente por OpenAI. Confirma también el grupo y la modalidad de facturación del token: un modelo que aparece en el catálogo público puede no estar autorizado para ese token. [Claves y errores de acceso](https://docs.laozhang.ai/api-manual), [grupos y facturación](https://docs.laozhang.ai/pricing).

![Relación entre el proveedor LaoZhang, la clave disponible para el Gateway y el modelo permitido al agente](https://blog.laozhang.ai/posts/es/openclaw-laozhang-ai-setup-guide/img/proveedor-clave-modelo.webp)

### La clave debe estar disponible para el proceso del Gateway

El ejemplo usa `${LAOZHANG_API_KEY}` como referencia a una variable de entorno. Configura esa variable mediante el mecanismo que ya utilice tu instalación para suministrar secretos al Gateway; no pegues la clave en el ejemplo ni la subas a Git.

OpenClaw consulta el entorno heredado del proceso y los archivos `.env` admitidos, entre ellos el del directorio de trabajo y `~/.openclaw/.env`. Esos archivos no sustituyen una variable que ya tenga valor en el entorno. Por tanto, una clave antigua heredada puede prevalecer sobre la nueva del archivo. Si la variable falta o está vacía, la sustitución queda sin resolver y se emite una advertencia. [Variables de entorno de OpenClaw](https://docs.openclaw.ai/gateway/configuration/environment-variables).

Exportar la variable en otra terminal no la entrega automáticamente a un servicio de `launchd`, `systemd` o a un contenedor ya iniciado. Comprueba el mecanismo de tu servicio sin imprimir ni compartir el secreto. El hecho de que un estado muestre una fuente de credenciales tampoco demuestra que esa clave tenga acceso a LaoZhang.

### Ejemplo para incorporar a tu configuración existente

OpenClaw usa por defecto `~/.openclaw/openclaw.json`, con sintaxis JSON5; `OPENCLAW_CONFIG_PATH` puede señalar otra ubicación. Guarda una copia recuperable de tu configuración antes de editarla. Si tu instalación distribuye la configuración en archivos incluidos, añade los campos en el archivo que ya sea responsable de ellos. **No reemplaces todo tu archivo por este ejemplo**: conserva tus agentes, herramientas, permisos y demás proveedores. [Configuración de OpenClaw](https://docs.openclaw.ai/gateway/configuration).

Este objeto muestra los campos que necesitas para una instalación con la política de modelos actual, introducida en OpenClaw v2026.8.1. El identificador `laozhang` es el nombre local del proveedor; `gpt-5.4-mini` es el identificador que se envía a LaoZhang.

```json
{
  "models": {
    "providers": {
      "laozhang": {
        "baseUrl": "https://api.laozhang.ai/v1",
        "apiKey": "${LAOZHANG_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "gpt-5.4-mini",
            "name": "GPT-5.4 mini en LaoZhang"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "laozhang/gpt-5.4-mini"
      },
      "modelPolicy": {
        "allow": ["laozhang/gpt-5.4-mini"]
      }
    }
  }
}
```

En una configuración ya utilizada, **añade la referencia a tu lista de permitidos existente**, sin borrar otras entradas aprobadas. El ejemplo deja una sola entrada para mostrar el tipo correcto: `modelPolicy.allow` es un array de cadenas con referencias `proveedor/modelo`. Si un agente define su propia política en `agents.entries.*.modelPolicy.allow`, esa política prevalece sobre la predeterminada. Añadir el modelo únicamente a los valores por defecto puede no autorizarlo para ese agente. [Selección y políticas de modelos](https://docs.openclaw.ai/concepts/models).

No hace falta declarar `models.mode: "merge"`: la combinación de inventarios es el comportamiento predeterminado. `replace` sirve para sustituir deliberadamente el inventario; no lo uses como arreglo general para una conexión fallida. Si existe una entrada del mismo proveedor en el `models.json` de un agente, una `baseUrl` no vacía puede prevalecer sobre la configuración central. Las credenciales con SecretRef tienen además reglas propias de prioridad. Revisa ese caso antes de concluir que OpenClaw ignora tu cambio. [Combinación de proveedores](https://docs.openclaw.ai/gateway/config-tools/custom-providers).

No añadimos cifras de contexto, límites de salida ni tarifas locales al objeto. Los metadatos que declares en OpenClaw no amplían los límites del proveedor ni cambian lo que LaoZhang factura; un campo de coste a cero tampoco convierte la API en gratuita.

### Si tu instalación conserva la antigua lista de modelos

No trates `agents.defaults.models` como si siempre fuera la lista de permitidos actual. En la documentación vigente ese mapa almacena alias y ajustes. Sin embargo, una configuración antigua aún no migrada puede conservar restricciones procedentes del esquema anterior. Identifica primero la versión y la política efectiva de tu instalación; conserva las restricciones y autoriza explícitamente la referencia que necesitas. [Política actual y migración](https://docs.openclaw.ai/concepts/models).

`doctor --fix` realiza reparaciones y puede modificar la configuración; no es una simple consulta. No lo ejecutes a ciegas para borrar un error de autorización: la reparación mantiene las restricciones que no puede resolver.

## Aplicar el cambio y comprobar una conversación real

La primera comprobación es estructural. La documentación ofrece `openclaw config validate` para validar la configuración contra el esquema de tu versión. Un JSON bien formado no demuestra que todos sus campos estén admitidos, que la variable se resuelva o que la clave sea válida. Nosotros solo hemos comprobado la sintaxis del bloque anterior sin conexión. [Validación de configuración](https://docs.openclaw.ai/gateway/configuration).

Los cambios de proveedor, modelo principal y modelos de respaldo se aplican en caliente con la configuración de recarga correspondiente. El modo predeterminado es `hybrid`; con la recarga desactivada, el cambio espera a un reinicio manual. Si una edición externa es inválida, el Gateway puede seguir usando la última configuración válida. Por eso, guardar el archivo no demuestra que el proceso haya aplicado el modelo nuevo. [Recarga de configuración](https://docs.openclaw.ai/gateway/configuration/hot-reload).

Comprueba la conexión por etapas, usando un turno pequeño y sin herramientas con efectos secundarios:

1. **Catálogo:** la lista de modelos debe incluir `laozhang/gpt-5.4-mini`. Eso confirma que la referencia está registrada, no que LaoZhang la haya aceptado.
2. **Agente:** comprueba el agente que utilizarás, su modelo principal y su política propia. Un valor por defecto no sustituye una elección específica del agente.
3. **Conversación:** en una conversación que tenga otro modelo fijado, `/model default` elimina esa elección. Después verifica el modelo efectivo; si seleccionas expresamente `laozhang/gpt-5.4-mini`, ten en cuenta que esa selección fija cambia el comportamiento de los modelos de respaldo.
4. **Respuesta:** envía una petición breve, por ejemplo «Responde con la palabra LISTO». Comprueba que el turno termina y que el registro disponible asocia la respuesta al proveedor y al modelo previstos.
5. **Correspondencia:** cuando tengas un identificador de solicitud o un registro de uso del proveedor, relaciónalo con ese turno. Una respuesta del asistente que diga «estoy usando GPT» no identifica por sí sola la ruta que atendió la petición.

La distinción entre valores predeterminados y selección de la conversación está documentada en [modelos de OpenClaw](https://docs.openclaw.ai/concepts/models). La diferencia entre inventario, estado y pruebas con llamadas reales aparece en [la CLI de modelos](https://docs.openclaw.ai/cli/models).

**Un resultado correcto de `models status`, incluso con `--check`, no sustituye la respuesta del turno.** Puede comprobar fuentes o estados de autenticación y resolver secretos sin demostrar que ese modelo haya completado tu petición. No uses `models scan` para descubrir modelos LaoZhang: esa función se dirige al inventario gratuito de OpenRouter y puede realizar comprobaciones reales y escribir configuración.

Tampoco lances `models status --probe` contra un Gateway activo como comprobación inocua. La prueba hace llamadas reales, puede consumir saldo y exige que un único proceso controle el estado, con el Gateway detenido y la limpieza completada antes de volver a usarlo. Para esta guía no se ha ejecutado ninguna de esas operaciones. [Condiciones de las pruebas de modelos](https://docs.openclaw.ai/cli/models).

## Comprobar las herramientas sin confundir texto con ejecución

Una respuesta de texto confirma solo una parte de la conexión. Para un agente que deba utilizar herramientas, comprueba además una operación que ya esté permitida y tenga un resultado conocido. No concedas permisos nuevos únicamente para pasar esta prueba.

Por ejemplo, si el agente ya puede leer archivos de un directorio de trabajo autorizado, prepara tú un archivo de prueba con una palabra aleatoria que no hayas incluido en el mensaje. Pide: «Lee el archivo de prueba con la herramienta disponible y devuelve su contenido». El resultado esperado no es que el asistente describa cómo lo haría: necesitas ver **la llamada de herramienta, el resultado devuelto y la respuesta final que utiliza ese resultado**, asociados al mismo turno y al modelo LaoZhang seleccionado.

![Esquema de comprobación del modelo efectivo y del ciclo de llamada, resultado de herramienta y respuesta final](https://blog.laozhang.ai/posts/es/openclaw-laozhang-ai-setup-guide/img/comprobar-herramientas.webp)

Si el agente no tiene ninguna herramienta de lectura autorizada, valida primero la respuesta de texto y deja pendiente la prueba de herramientas. El acceso a un modelo que admite herramientas no otorga permisos al agente ni garantiza que cualquier herramienta o formato de streaming funcione.

En Chat Completions, una respuesta puede contener `tool_calls` y texto vacío: eso puede ser una solicitud de herramienta válida, no un fallo de red. El cliente debe procesar la llamada y devolver su resultado para que el modelo continúe. Los fragmentos `delta` del streaming también deben ensamblarse correctamente. [Respuesta y herramientas de Chat Completions](https://docs.laozhang.ai/api-reference/chat-completions).

Si fallan las herramientas mientras el texto funciona, revisa el modelo, el formato enviado por el adaptador, los parámetros y los permisos de esa herramienta. LaoZhang documenta errores de parámetros para algunas combinaciones de GPT-6, herramientas de Chat Completions, esfuerzo de razonamiento y `max_tokens`. No copies los parámetros de otro modelo como receta universal; `max_tokens` y `max_completion_tokens` tampoco son intercambiables para todos ellos. [Compatibilidad de integración](https://docs.laozhang.ai/scenarios).

## Qué revisar cuando aparece un error

El código HTTP orienta la siguiente comprobación, pero el cuerpo del error decide qué ha rechazado el proveedor. No envíes claves ni registros completos con secretos al pedir ayuda. [Errores documentados de LaoZhang](https://docs.laozhang.ai/api-manual).

| Síntoma | Primera comprobación útil |
| --- | --- |
| `Model not allowed` | Revisa la política efectiva del agente, la referencia completa y cualquier restricción antigua pendiente de migración. No abras la lista a todos los modelos. |
| 401 | Comprueba que usas una API Key de LaoZhang y que el proceso actual recibe el valor esperado. Un AccessToken o una clave de OpenAI no sirve para esta ruta. |
| 403 | Revisa los permisos del token y el grupo al que pertenece. Que el modelo figure públicamente no prueba el acceso de tu cuenta. |
| 404 | Comprueba `baseUrl`, la ruta del protocolo y el identificador exacto del modelo. Busca recursos o `/v1` duplicados. |
| 400 | Lee qué parámetro o límite de contexto se ha rechazado. Revisa el formato del protocolo antes de cambiar credenciales. |
| 429 | Distingue saldo, capacidad y límites de peticiones según el cuerpo del error. Repetir una petición sin resolver el saldo no ayuda. |
| 5xx o tiempo de espera agotado | Conserva hora e identificador de la solicitud, si existe, y distingue la respuesta del servicio de un fallo en tu conexión. |
| Sigue respondiendo el modelo anterior | Comprueba la selección de la conversación, los ajustes del agente, la prioridad de `models.json` y si se aplicó la última configuración válida. |

Los modelos de respaldo pueden recuperar determinados fallos, pero no son una solución universal. OpenClaw intenta primero la recuperación admitida para el mismo modelo y después recorre los respaldos configurados. Entre los fallos que pueden permitirlo están autenticación, límite de peticiones, facturación o modelo ausente; el desbordamiento de contexto y una negativa final no garantizan ese cambio. Una elección explícita de modelo en la conversación se mantiene estricta. [Comportamiento de los respaldos](https://docs.openclaw.ai/concepts/model-failover).

Dos modelos del mismo proveedor también pueden compartir una interrupción o la falta de saldo. Antes de añadir uno como respaldo, confirma su acceso, protocolo y política; no supongas que el segundo será más barato o resolverá el primer error.

## Cuánto cuesta un turno y cómo limitar las pruebas

LaoZhang factura el consumo real con saldo prepago. Las tarifas, el grupo del token y la modalidad de facturación determinan la deducción; el consumo del panel es la referencia para la factura. La documentación no establece un descuento empresarial fijo aplicable a todos los modelos. [Facturación de LaoZhang](https://docs.laozhang.ai/pricing).

El catálogo consultado el 7 de octubre de 2026 muestra para `gpt-5.4-mini` **0,75 USD por millón de tokens de entrada**, **4,50 USD por millón de salida** y **0,075 USD por millón de lectura de caché**. Revisa la tarifa y tu grupo antes de llamar. [Tarifas del modelo](https://docs.laozhang.ai/models).

Como cálculo ilustrativo, una petición con **10.000 tokens de entrada sin caché y 1.000 de salida**, sin otros cargos y con multiplicador de grupo igual a 1, costaría:

```text
Entrada: 10.000 / 1.000.000 × 0,75 USD = 0,0075 USD
Salida:   1.000 / 1.000.000 × 4,50 USD = 0,0045 USD
Total hipotético:                         0,0120 USD
```

Es una operación aritmética, no un cargo observado ni una estimación mensual. Un turno de agente puede incluir varias peticiones al modelo: historial, instrucciones, resultados de herramientas y nuevos intentos alteran el consumo. Empieza con una respuesta corta y una sola herramienta de lectura; revisa el uso antes de habilitar un trabajo largo. La caché solo reduce la parte que el proveedor identifique y facture como lectura de caché, no toda la conversación.

## Preguntas frecuentes

### ¿Puedo conectar LaoZhang con mi suscripción de ChatGPT?

Necesitas una API Key de LaoZhang y acceso aprobado a su servicio. Una suscripción de ChatGPT o una referencia de modelo en OpenClaw no demuestra que tengas saldo o permisos en ese proveedor. La ruta descrita utiliza la facturación prepago de LaoZhang. [Acceso y servicio](https://docs.laozhang.ai/).

### ¿Por qué el modelo aparece en la lista, pero mi agente no lo usa?

La lista confirma que el modelo está registrado. Revisa el modelo principal y la política del agente, la selección fijada en la conversación y la configuración realmente aplicada. Usa `/model default` si quieres eliminar la elección particular de esa conversación y después comprueba el modelo efectivo. [Selección de modelos](https://docs.openclaw.ai/concepts/models).

### ¿Puedo utilizar un modelo Claude con esta configuración?

El catálogo consultado el 7 de octubre de 2026 indica que los modelos Claude están temporalmente fuera de servicio por falta de recursos. No migres una configuración antigua de Sonnet u Opus suponiendo que sigue disponible. Cuando cambie la oferta, comprueba el acceso de tu token y el protocolo apropiado. [Disponibilidad de modelos](https://docs.laozhang.ai/models).

### ¿Debo reiniciar el Gateway cada vez que cambio el modelo?

Con la recarga adecuada, los cambios de modelos y proveedores se aplican en caliente. Si la recarga está desactivada, necesitas el reinicio manual previsto en tu instalación. Una edición inválida puede dejar activa la última configuración válida; comprueba el resultado del cambio antes de atribuirlo al proveedor. [Recarga de OpenClaw](https://docs.openclaw.ai/gateway/configuration/hot-reload).

### ¿Una respuesta vacía significa que LaoZhang ha fallado?

No necesariamente. En Chat Completions, `tool_calls` puede acompañar a un contenido textual vacío mientras el modelo espera el resultado de una herramienta. Comprueba si hay una llamada pendiente y si OpenClaw ha completado ese ciclo; un turno sin llamada ni respuesta final requiere una investigación distinta. [Formato de las respuestas](https://docs.laozhang.ai/api-reference/chat-completions).

## Fuentes

Páginas externas que cita esta guía, en el orden en que aparecen. Última actualización: 2026-10-07.

- [proveedores personalizados de OpenClaw](https://docs.openclaw.ai/gateway/config-tools/custom-providers) (docs.openclaw.ai)
- [Variables de entorno de OpenClaw](https://docs.openclaw.ai/gateway/configuration/environment-variables) (docs.openclaw.ai)
- [Configuración de OpenClaw](https://docs.openclaw.ai/gateway/configuration) (docs.openclaw.ai)
- [Selección y políticas de modelos](https://docs.openclaw.ai/concepts/models) (docs.openclaw.ai)
- [Recarga de configuración](https://docs.openclaw.ai/gateway/configuration/hot-reload) (docs.openclaw.ai)
- [la CLI de modelos](https://docs.openclaw.ai/cli/models) (docs.openclaw.ai)
- [Comportamiento de los respaldos](https://docs.openclaw.ai/concepts/model-failover) (docs.openclaw.ai)