Configuración completa de 5 pasos para integrar OpenClaw con la API de Claude: solucione errores de invocación de herramientas con el formato Anthropic Messages

¿Te has encontrado con este error al ejecutar modelos de Claude con OpenClaw?

400 ... ValidationException: Operation not allowed

El chat normal funciona bien, pero en cuanto llega la llamada a herramientas (tool use), todo falla estrepitosamente. Este es un bache en el que caen casi todos los usuarios de OpenClaw al conectar con la API de Claude.

La causa raíz es solo una: estás usando el formato de API incorrecto.

OpenClaw ofrece dos opciones de formato para conectar con Claude: openai-completions y anthropic-messages. Al usar el modo de compatibilidad con OpenAI, el chat básico funciona, pero al entrar en el ciclo de llamadas de herramientas de varios turnos (tool_calls → tool_result → tool loop), la solicitud es rechazada. Solo al cambiar al formato anthropic-messages, las llamadas a herramientas funcionan de manera estable.

Basándonos en configuraciones verificadas mediante pruebas reales, te enseñaremos paso a paso cómo completar la configuración correcta de OpenClaw con la API de Claude utilizando APIYI (apiyi.com) como proveedor de servicio proxy de API.

Análisis del problema central al integrar la API de Claude en OpenClaw

Antes de darte la solución, entendamos por qué ocurre el error.

¿Qué es OpenClaw?

OpenClaw es uno de los marcos de trabajo de Agentes de IA de código abierto más populares para 2025-2026, desarrollado por Peter Steinberger (fundador de PSPDFKit). Sus características principales son:

• Soporte multiplataforma: Signal, Telegram, Discord, WhatsApp, iMessage.
• Acceso a múltiples modelos: Claude, GPT, DeepSeek y otros modelos principales.
• Capacidad de llamada a herramientas: Más de 50 integraciones integradas, soporte para ejecución de código, búsqueda web, domótica, etc.
• Ejecución local: La configuración y el historial de conversaciones se almacenan localmente, protegiendo la privacidad.

Características principales de OpenClaw	Descripción
Desarrollador	Peter Steinberger (fundador de PSPDFKit)
Licencia	Código abierto y gratuito
Plataformas compatibles	Signal / Telegram / Discord / WhatsApp / iMessage
Modelos compatibles	Claude / GPT / DeepSeek, etc.
Formatos de API	openai-completions / anthropic-messages
Integración de herramientas	Más de 50 integraciones integradas
Almacenamiento de datos	Almacenamiento local, privacidad controlada

Diferencias fundamentales entre los dos formatos de API

OpenClaw admite dos formas de acceder a la API de Claude:

Dimensión de comparación	openai-completions	anthropic-messages
Ruta del endpoint	/v1/chat/completions	/v1/messages
Chat de solo texto	✅ Normal	✅ Normal
Llamada a herramientas (tool use)	❌ Error 400	✅ Estable y disponible
Ciclo de herramientas de varios turnos	❌ Error	✅ Estable y disponible
Caché de indicaciones (Prompt Caching)	❌ No compatible	✅ Compatible
Pensamiento extendido (Extended Thinking)	⚠️ Incompleto	✅ Soporte completo
Requisitos de encabezado	Sin requisitos especiales	Requiere anthropic-version

🎯 Sugerencia técnica: Al integrar la API de Claude en OpenClaw, es obligatorio usar el formato anthropic-messages para utilizar de forma estable la función de llamada a herramientas. Recomendamos usar APIYI (apiyi.com) como proveedor de servicio proxy de API, ya que esta plataforma ofrece soporte completo para el formato nativo de la API de Messages de Anthropic.

¿Por qué falla la llamada a herramientas con el formato openai-completions?

Cuando OpenClaw utiliza el formato openai-completions para llamar a Claude, sucede lo siguiente:

1. Conversión de formato: OpenClaw envía los campos tool_calls y function en formato OpenAI.
2. Incompatibilidad de protocolo: Claude utiliza de forma nativa los formatos tool_use y tool_result.
3. Conflicto de varios turnos: El ciclo de herramientas (tool loop) requiere mantener la consistencia del tool_use_id entre múltiples solicitudes; esta información se pierde fácilmente durante la conversión de formato.
4. Rechazo de validación: El servicio proxy o la API ascendente detectan que el formato no coincide y devuelven un 400 ValidationException.

Configuración completa de OpenClaw para la API de Claude: 5 pasos

La siguiente configuración se basa en pruebas reales utilizando APIYI (apiyi.com) como servicio proxy de API para la API de Claude.

Paso 1: Configurar el Provider (Configuración principal)

Añade la siguiente configuración en la sección models.providers de tu archivo openclaw.json:

{
  "models": {
    "providers": {
      "apiyi": {
        "baseUrl": "https://api.apiyi.com",
        "apiKey": "sk-TU_CLAVE_APIYI",
        "api": "anthropic-messages",
        "headers": {
          "anthropic-version": "2023-06-01",
          "anthropic-beta": ""
        },
        "models": [
          {
            "id": "claude-opus-4-6",
            "name": "claude-opus-4-6",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 200000,
            "maxTokens": 16384
          },
          {
            "id": "claude-sonnet-4-6-thinking",
            "name": "claude-sonnet-4-6-thinking",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 200000,
            "maxTokens": 16384
          }
        ]
      }
    }
  }
}

Detalles clave de la configuración:

Opción	Valor correcto	Descripción
baseUrl	https://api.apiyi.com	No incluyas /v1, de lo contrario la ruta se concatenará como .../v1/v1/messages
api	"anthropic-messages"	Es obligatorio usar este valor; no utilices openai-completions
anthropic-version	"2023-06-01"	Debe incluirse, de lo contrario la solicitud será rechazada
anthropic-beta	"" (cadena vacía)	Desactiva forzosamente las funciones beta para evitar errores 400
reasoning	false	Desactiva el campo thinking para evitar un ValidationException
streaming	Se recomienda false	Desactivar el streaming es más estable en escenarios de servicio proxy de API

💡 Nota importante: Por nada del mundo escribas la baseUrl como https://api.apiyi.com/v1. Cuando OpenClaw usa el formato anthropic-messages, añade automáticamente /v1/messages. Si tu URL ya incluye /v1, la ruta final será /v1/v1/messages, lo que provocará un error 404.

Paso 2: Registrar la lista de permitidos (allowlist)

Debes añadir los modelos a agents.defaults.models. Si no lo haces, OpenClaw indicará que el modelo "no está registrado o no está permitido" y hará un fallback silencioso a otro modelo, una trampa muy sutil que puede confundirte.

{
  "agents": {
    "defaults": {
      "models": {
        "apiyi/claude-opus-4-6": { "streaming": false },
        "apiyi/claude-sonnet-4-6-thinking": { "streaming": false }
      }
    }
  }
}

Paso 3: Configurar el Agent

Tomando como ejemplo el agent de tareas (tasks):

{
  "agents": {
    "list": [
      {
        "id": "tasks",
        "model": "apiyi/claude-opus-4-6",
        "tools": {
          "profile": "coding",
          "alsoAllow": ["group:web"]
        }
      }
    ]
  }
}

Paso 4: Gestionar sesiones existentes (Muy fácil de olvidar)

Este es el paso que más se suele pasar por alto. Incluso si modificas la configuración, las sesiones de canal existentes pueden tener guardado el modelProvider/model anterior, haciendo que parezca que los cambios no han surtido efecto.

Tienes dos formas de solucionarlo:

Método A: Parchear el modelo de la sesión actual

openclaw gateway call sessions.patch \
  --params '{"key":"agent:tasks:discord:channel:<ID_DEL_CANAL>","model":"apiyi/claude-opus-4-6"}'

Método B: Reiniciar la sesión (borra el historial de chat)

openclaw gateway call sessions.reset \
  --params '{"key":"agent:tasks:discord:channel:<ID_DEL_CANAL>","reason":"reset"}'

🚀 Inicio rápido: Tras registrarte en la plataforma APIYI (apiyi.com), obtendrás tu clave API. Sustituye sk-TU_CLAVE_APIYI en la configuración anterior por tu clave real para completar la integración de Claude API en OpenClaw.

Paso 5: Verificar que la configuración funcione

Ejecuta los siguientes comandos para confirmar que todo es correcto:

# Comprobar el estado del modelo
openclaw models status --agent tasks

# Enviar un mensaje de prueba
openclaw agent --agent tasks --message "Responde solo pong" --json

En el JSON de respuesta, verifica que meta.agentMeta.provider y meta.agentMeta.model coincidan con lo esperado:

{
  "meta": {
    "agentMeta": {
      "provider": "apiyi",
      "model": "claude-opus-4-6"
    }
  }
}

Si el provider o el modelo no son los que configuraste, significa que el problema de la sesión persistente sigue ahí; vuelve al paso 4.

Errores comunes y solución de problemas en OpenClaw + Claude

Durante la configuración, podrías encontrarte con los siguientes problemas:

Error 1: 400 ValidationException: Operation not allowed

400 ... ValidationException: Operation not allowed

Causa: La solicitud incluye los campos thinking o output_config. Algunos servicios proxy no soportan estos parámetros para los modelos Claude 4.6.

Solución:

1. Asegúrate de que en la configuración del modelo reasoning: false.
2. Verifica que el encabezado sea anthropic-beta: "" (cadena vacía).
3. Comprueba si tu versión de OpenClaw está enviando campos relacionados con thinking.

Error 2: 404 Not Found

Causa: La baseUrl está mal configurada (incluye un /v1 extra).

Solución: Cambia la baseUrl a https://api.apiyi.com (sin el /v1).

Error 3: Fallback silencioso del modelo

Síntoma: El estilo de las respuestas cambia de repente o el modelo dice no ser Claude.

Causa: El modelo no se añadió a la allowlist, por lo que OpenClaw cambió automáticamente al modelo por defecto.

Solución: Registra todos los modelos que vayas a usar en agents.defaults.models.

Error 4: Fallo en el bucle de llamada a herramientas

Síntoma: La primera llamada a la herramienta funciona, pero falla al devolver el tool_result.

Causa: Estás usando el formato openai-completions y el tool_use_id necesario para el bucle se pierde en la conversión.

Solución: Cambia al formato api: "anthropic-messages".

Por qué elegir APIYI como servicio proxy de API de Claude para OpenClaw

Al elegir un servicio proxy de API, hay varios factores clave a tener en cuenta.

Comparativa de selección de servicios proxy de API para Claude

Dimensión de evaluación	Conexión directa con Anthropic	APIYI (apiyi.com)	Otros servicios proxy
Formato Anthropic Messages	✅ Soporte nativo	✅ Soporte completo	⚠️ Soporte parcial
Invocación de herramientas (tool use)	✅ Soporte	✅ Soporte estable	⚠️ Podría ser inestable
Prompt Caching	✅ Soporte	✅ Soporte	❌ La mayoría no lo soporta
Conexión directa	❌ Requiere proxy	✅ Disponible directamente	✅ Algunos disponibles
Interfaz unificada multimodelo	❌ Solo Claude	✅ Claude + GPT + más	✅ Soporte parcial
Pago por uso	✅ Precios oficiales	✅ Facturación flexible	⚠️ Precios poco transparentes
Verificación con OpenClaw	–	✅ Verificado	⚠️ No verificado

💰 Optimización de costes: APIYI (apiyi.com) es compatible con el formato nativo de la API de Messages de Anthropic. Esto significa que, al usarlo en OpenClaw, tus solicitudes pueden beneficiarse de los descuentos por Prompt Caching de Claude: el coste de los tokens de entrada que coincidan con la caché es solo el 10% del precio base.

Las 3 ventajas principales de APIYI

1. Soporte completo del formato nativo de Anthropic

La plataforma APIYI no es un simple reenvío de formato OpenAI, sino que ofrece soporte completo para la API de Messages de Anthropic (endpoint /v1/messages), incluyendo:

• Parámetro de control de caché cache_control
• Formato nativo de invocación de herramientas tool_use / tool_result
• Encabezado de solicitud anthropic-version
• Pensamiento extendido (Extended Thinking)

2. Verificado mediante pruebas reales con OpenClaw

Todas las configuraciones de este artículo se basan en pruebas reales en la plataforma APIYI, garantizando que:

• Los ciclos de invocación de herramientas de múltiples turnos funcionen de manera estable.
• El tool_use_id se transfiera correctamente entre múltiples solicitudes.
• No se pierda el contexto en escenarios de conversaciones largas.

3. Gestión unificada de múltiples modelos

Con una sola clave API puedes invocar varios modelos como Claude, GPT, DeepSeek, etc. En OpenClaw, puedes configurar diferentes modelos para diferentes agentes y cambiar entre ellos con flexibilidad.

Trucos de configuración avanzada para conectar OpenClaw a la API de Claude

Una vez que domines la configuración básica, estos trucos te ayudarán a optimizarla aún más.

Truco 1: Configurar diferentes modelos para diferentes agentes

{
  "agents": {
    "list": [
      {
        "id": "tasks",
        "model": "apiyi/claude-opus-4-6",
        "tools": { "profile": "coding" }
      },
      {
        "id": "chat",
        "model": "apiyi/claude-sonnet-4-6-thinking",
        "tools": { "profile": "default" }
      }
    ]
  }
}

• Agente de tareas (tasks agent): Usa Opus 4.6 para manejar tareas complejas y generación de código.
• Agente de chat (chat agent): Usa Sonnet 4.6 para conversaciones diarias, con un coste menor.

Truco 2: Aprovechar el Prompt Caching para reducir costes

Dado que APIYI soporta el formato nativo de Anthropic, la indicación del sistema (system prompt) de OpenClaw puede almacenarse automáticamente en caché. Para agentes con indicaciones del sistema largas, el coste de entrada tras un acierto en caché es de solo el 10%.

Truco 3: Notas de seguridad

• No expongas tu clave API en canales públicos de Discord.
• La clave en openclaw.json se almacena en texto plano; asegúrate de que los permisos del archivo sean correctos.
• Si sospechas que tu clave se ha filtrado, cámbiala inmediatamente en el panel de control de APIYI (apiyi.com).

Preguntas frecuentes (FAQ) sobre la integración de OpenClaw con la API de Claude

P1: ¿Es obligatorio usar un servicio proxy para usar Claude en OpenClaw?

No es obligatorio, pero es muy recomendable para usuarios en China. La conexión directa a la API de Anthropic requiere un entorno de red en el extranjero, mientras que a través del servicio proxy de API de APIYI (apiyi.com) se puede realizar la invocación del modelo de forma directa, disfrutando al mismo tiempo del soporte completo de la API de Anthropic Messages.

P2: ¿Por qué cambió la configuración pero el comportamiento de OpenClaw no?

Este es el problema más común; el 99% de las veces se debe a que la sesión existente tiene la configuración antigua en caché. Utilice los comandos sessions.patch o sessions.reset para actualizar la sesión, o realice la prueba en un canal nuevo. Consulte el paso 4 para ver los comandos específicos.

P3: ¿Se puede usar la función "thinking" de Claude 4.6 en OpenClaw?

Actualmente, en los enlaces de proxy, el campo thinking (thinking / output_config) podría activar una 400 ValidationException. Se recomienda establecer reasoning: false y seguir el estado de soporte de la función thinking a través de las actualizaciones de la plataforma APIYI (apiyi.com).

P4: ¿Se puede usar una sola clave de APIYI para varios agentes de OpenClaw al mismo tiempo?

Sí. La clave API de APIYI no limita el número de agentes concurrentes; puede configurar la misma clave para diferentes agentes como tasks, chat o coder, y se facturará según el uso real de tokens.

P5: ¿Es normal la latencia en la llamada a herramientas de Claude en OpenClaw?

Las llamadas a herramientas implican múltiples rondas de solicitudes a la API (enviar solicitud → obtener tool_use → ejecutar herramienta → devolver tool_result → obtener respuesta final), por lo que suelen ser más lentas que un chat puro. A través del enlace de proxy de baja latencia de APIYI (apiyi.com), se puede mantener la latencia de cada ronda de invocación de la API dentro de un rango razonable.

Resumen: 3 puntos clave para integrar OpenClaw con la API de Claude

Basándonos en la configuración probada en este artículo, estos son los puntos clave que debe recordar al integrar OpenClaw con la API de Claude:

1. Debe usar el formato anthropic-messages: Establezca api: "anthropic-messages". Este es el requisito previo para que las llamadas a herramientas funcionen de manera estable; el formato openai-completions dará un error 400 en llamadas a herramientas de varias rondas.
2. 3 errores comunes a evitar: baseUrl sin /v1, desactivar anthropic-beta y reasoning, y gestionar el caché de la sesión existente.
3. Elija el proveedor de servicios proxy adecuado: APIYI (apiyi.com) ofrece soporte completo para la API nativa de Anthropic Messages, verificado mediante pruebas reales con OpenClaw; tanto las llamadas a herramientas como el Prompt Caching están disponibles y son estables.

Se recomienda utilizar APIYI (apiyi.com) para completar rápidamente la configuración de OpenClaw con la API de Claude; podrá poner en marcha las llamadas a herramientas en solo 5 minutos.

Referencias

1. Documentación oficial de OpenClaw – Model Providers: Instrucciones de configuración de proveedores de modelos

   • Enlace: docs.openclaw.ai/concepts/model-providers

2. Documentación oficial de Anthropic – Messages API: Formato de invocación nativo de la API de Claude

   • Enlace: platform.claude.com/docs/en/api/messages

3. Documentación oficial de Anthropic – Compatibilidad con el SDK de OpenAI: Limitaciones de funciones en el modo de compatibilidad

   • Enlace: platform.claude.com/docs/en/api/openai-sdk

4. Repositorio de GitHub de OpenClaw: Código fuente abierto y discusiones de Issues

   • Enlace: github.com/openclaw/openclaw

---

📝 Autor: APIYI Team | Equipo técnico de APIYI, enfocado en la integración de API de Modelos de Lenguaje Grande y el intercambio de conocimientos técnicos. Visita apiyi.com para obtener más tutoriales técnicos y claves API.