[La herramienta de imagen devuelve error 401 de token Bearer no válido con API de Anthropic] - Image Tool Returns 401 Invalid Bearer Token Error with Anthropic API

Manifestación del error principal

La herramienta de análisis de imágenes falla con un error de autenticación 401 al procesar capturas de pantalla o solicitudes de visión a través de la API de Anthropic:

Error: Invalid bearer token (401)
    at AnthropicProvider.analyzeImage (/app/src/providers/anthropic.ts:142:12)
    at ImageTool.execute (/app/src/tools/image.ts:67:15)
    at processTicksAndTriggerCallbacks (node:internal/process/task_queues:95:5)

Image/vision tool auth error — cannot analyze screenshots for ADB-based browsing
TypeError: Invalid bearer token (401)

Verificación a nivel de red

Capturar la solicitud HTTP real revela el encabezado mal configurado:

# Incorrect request being sent (current behavior)
$ curl -v -X POST https://api.anthropic.com/v1/messages \
  -H "Authorization: Bearer sk-ant-..." \
  -H "Content-Type: application/json"

< HTTP/2 401
< content-type: application/json
{"type":"error","error":{"type":"authentication_error","message":"Invalid bearer token"}}

Operaciones afectadas

Las siguientes operaciones activan el fallo de autenticación:

• Herramienta de Imagen: Invocaciones directas de la herramienta image para análisis de capturas de pantalla
• Cron Jobs: Tareas de automatización programadas que realizan análisis basado en visión
• Threads Browse: Flujos de trabajo de análisis de capturas de pantalla ADB de Seeker
• Llamadas a la API de Visión: Cualquier llamada al endpoint messages con contenido de imagen

Contexto de versión

Confirmado afectado en OpenClaw versión 2026.2.6-3. El problema se origina en la implementación del cliente del proveedor de Anthropic donde la construcción del encabezado diverge de la especificación oficial de la API.

Punto de fallo arquitectónico

El cliente del proveedor de Anthropic implementa incorrectamente la autenticación OAuth-style Bearer (Authorization: Bearer <token>) en lugar del método de autenticación con clave API que requiere la API de Anthropic.

Análisis técnico

La API oficial de Anthropic utiliza un mecanismo de autenticación distintivo:

Análisis de la ruta del código

El fallo ocurre en la capa de construcción de solicitudes del proveedor:

// lib/providers/anthropic.ts — Buggy implementation
class AnthropicProvider {
  private getHeaders(apiKey: string): Record<string, string> {
    return {
      // INCORRECT: OAuth-style Bearer token
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
      'anthropic-version': '2023-06-01',
      'anthropic-dangerous-direct-browser-access': 'true'
    };
  }
}

Por qué ocurre esto

El proveedor de Anthropic probablemente fue implementado adaptando código de proveedores que utilizan autenticación con token Bearer OAuth 2.0 (como OpenAI, OpenRouter, o puertas de enlace LLM genéricas). Anthropic diverge de este patrón al requerir la clave API sin procesar en un encabezado dedicado x-api-key.

Secuencia del fallo

1. El usuario configura la variable de entorno ANTHROPIC_API_KEY
2. La herramienta de imagen invoca el método analyzeImage()
3. El proveedor construye la solicitud HTTP con Authorization: Bearer sk-ant-...
4. La API de Anthropic rechaza la solicitud con 401 Invalid bearer token
5. El error se propaga a través de la pila de llamadas hasta el usuario

Fase 1: Identificar el archivo afectado

Localizar la implementación del proveedor de Anthropic:

# Standard installation paths
find . -path "*/providers/anthropic*" -name "*.ts" 2>/dev/null
find ~/.openclaw -name "anthropic.ts" 2>/dev/null

# Common Docker container path
docker exec <container-name> find /app -name "anthropic.ts" 2>/dev/null

Fase 2: Aplicar la corrección del encabezado

Reemplazar el encabezado Authorization: Bearer con x-api-key:

Antes (Incorrecto):

// lib/providers/anthropic.ts
private getHeaders(apiKey: string): Record<string, string> {
  return {
    'Authorization': `Bearer ${apiKey}`,  // ❌ WRONG
    'Content-Type': 'application/json',
    'anthropic-version': '2023-06-01',
    'anthropic-dangerous-direct-browser-access': 'true'
  };
}

Después (Correcto):

// lib/providers/anthropic.ts
private getHeaders(apiKey: string): Record<string, string> {
  return {
    'x-api-key': apiKey,  // ✅ CORRECT
    'Content-Type': 'application/json',
    'anthropic-version': '2023-06-01',
    'anthropic-dangerous-direct-browser-access': 'true'
  };
}

Fase 3: Verificar que no existan otras referencias a Bearer

Asegurarse de que no existe uso adicional de tokens Bearer en el archivo:

grep -n "Bearer" lib/providers/anthropic.ts
grep -n "Authorization.*Bearer" lib/providers/anthropic.ts

Salida esperada: Sin coincidencias después de la corrección.

Fase 4: Reiniciar los servicios

# Local installation
pkill -f openclaw
openclaw &

# Docker container
docker restart <container-name>

# Kubernetes
kubectl rollout restart deployment/openclaw -n default

Método 1: Prueba directa de API

Validar que el encabezado de autenticación esté correctamente formateado:

# Test the Anthropic API directly with x-api-key header
curl -s -X POST "https://api.anthropic.com/v1/messages" \
  -H "x-api-key: ${ANTHROPIC_API_KEY}" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 10,
    "messages": [{"role": "user", "content": "test"}]
  }' | jq .

Salida esperada (éxito):

{
  "id": "msg_...",
  "type": "message",
  "role": "assistant",
  "content": [...]
}

Método 2: Prueba de herramienta OpenClaw

Ejecutar un análisis de imagen de prueba a través de la CLI:

# Test image tool with local screenshot
openclaw run --image "/tmp/test-screenshot.png" "Describe this image"

# Expected: Successful analysis without 401 error

Método 3: Script de prueba de integración

Crear y ejecutar un script de verificación:

cat > /tmp/verify_anthropic_auth.sh << 'EOF'
#!/bin/bash
set -e

echo "Testing Anthropic API authentication..."

RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "https://api.anthropic.com/v1/messages" \
  -H "x-api-key: ${ANTHROPIC_API_KEY}" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 10,
    "messages": [{"role": "user", "content": "ping"}]
  }')

HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
BODY=$(echo "$RESPONSE" | head -n-1)

if [ "$HTTP_CODE" = "200" ]; then
  echo "✅ Authentication successful (HTTP 200)"
  exit 0
else
  echo "❌ Authentication failed (HTTP $HTTP_CODE)"
  echo "Response: $BODY"
  exit 1
fi
EOF

chmod +x /tmp/verify_anthropic_auth.sh
/tmp/verify_anthropic_auth.sh

Método 4: Verificación de Cron Job

Para tareas automatizadas, agregar registro de diagnóstico:

# Verify cron job logs show successful authentication
journalctl -u openclaw-cron -n 50 | grep -E "(anthropic|vision|image|401)"

# Or check the cron job output directly
cat /var/log/openclaw/cron.log | tail -20

Esperado: Sin errores de 401 o Invalid bearer token en los registros.

Error común 1: Imágenes Docker en caché

Si se ejecuta OpenClaw en Docker, asegurar reconstruir la imagen después de modificar el código del proveedor:

# Incorrect: Container restart won't apply code changes
docker restart openclaw

# Correct: Rebuild and recreate the container
docker build -t openclaw:fixed .
docker stop openclaw && docker rm openclaw
docker run -d --name openclaw openclaw:fixed

Error común 2: Configuración de múltiples proveedores

OpenClaw puede tener proveedores de respaldo configurados. Verificar que se esté utilizando el proveedor correcto:

# Check active provider configuration
openclaw config list | grep -A5 anthropic

# Verify environment variable precedence
env | grep -i anthropic

Error común 3: Formato de clave API incompatible

Asegurarse de que la clave API tenga el formato correcto (las claves de Anthropic comienzan con sk-ant-):

# Validate key format
echo $ANTHROPIC_API_KEY | grep -E "^sk-ant-"
# Should output the key; no output means incorrect format

Error común 4: Anulación de URL base

Algunas configuraciones redirigen las llamadas de Anthropic a través de proxies (OpenRouter) que esperan una autenticación diferente:

# If using OpenRouter proxy, Bearer tokens ARE correct
openclaw config get providers.anthropic.baseURL
# Should be empty or https://api.anthropic.com (not openrouter)

Error común 5: Caché de módulos de Node

Las cachés de compilación de TypeScript pueden impedir que las correcciones surtan efecto:

# Clear build cache
rm -rf node_modules/.cache
rm -rf dist/

# Rebuild
npm run build

# Or for TypeScript watch mode
npm run build:watch &

Error común 6: Versión incorrecta en el encabezado

Anthropic requiere el encabezado de versión exacto. Verificar:

# Correct version header (as of 2024)
anthropic-version: 2023-06-01

# Incorrect versions will cause errors
anthropic-version: 2023-01-01  # ❌ Too old
anthropic-version: latest      # ❌ Not accepted

Error común 7: Almacenamiento de credenciales en Keychain de macOS

En macOS, las claves API almacenadas en Keychain pueden no actualizarse cuando cambian las variables de entorno:

# Remove cached Keychain entry and rely on environment variable
security delete-generic-password -s "OpenClaw" -a "anthropic_api_key"

# Or update the Keychain entry
security add-generic-password -s "OpenClaw" -a "anthropic_api_key" -w "sk-ant-your-key"

Directamente relacionados

• 401 authentication_error: Invalid bearer token — Síntoma principal; ocurre cuando el encabezado Bearer se envía a Anthropic
• 401 authentication_error: Incorrect API key — Error similar pero indica formato de clave incorrecto, no encabezado incorrecto
• 401 authentication_error: No API key provided — Falta el encabezado x-api-key por completo

Contextualmente relacionados

• Fallos de la herramienta de imagen — Categoría general de errores cuando el análisis de visión/capturas de pantalla falla
• Dependencia del proxy de OpenRouter — Cuando los usuarios solucionan el error enrutando a través de OpenRouter
• Activadores de respaldo de proveedor — El error puede cascadear a proveedores de respaldo si están configurados

Referencia histórica

Referencias externas

• Documentación de autenticación de la API de Anthropic — Referencia oficial para el formato correcto del encabezado
• Referencia de la API de Anthropic — Requisitos completos de encabezados para todos los endpoints