Configura Anthropic Claude en OpenClaw: Guía rápida

¿Alguna vez has sentido que configurar el acceso a modelos de IA es más difícil que escribir el código en sí? Gestionar diferentes métodos de autenticación y parámetros específicos para cada modelo puede quitarte mucho tiempo. OpenClaw simplifica este proceso para que puedas centrarte en lo que importa y aprovechar Claude al máximo.

Anthropic (Claude)

Anthropic desarrolla la familia de modelos Claude y ofrece acceso mediante una API. En OpenClaw puedes autenticarte con una API key o un setup-token.

Opción A: Anthropic API key

Ideal para: acceso estándar a la API y facturación basada en el uso. Crea tu API key en la Anthropic Console.

Configuración de la CLI

openclaw onboard
# choose: Anthropic API key

# or non-interactive
openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"

Snippet de configuración de Claude CLI

{
  env: { ANTHROPIC_API_KEY: "sk-ant-..." },
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}

Configuración de Thinking por defecto (Claude 4.6)

• Los modelos Anthropic Claude 4.6 usan por defecto el modo adaptive thinking en OpenClaw si no se define un nivel específico.
• Puedes cambiarlo por mensaje (/think:<level>) o en los parámetros del modelo: agents.defaults.models["anthropic/<model>"].params.thinking.
• Revisa la configuración de tus agentes para ajustar estos valores según tus necesidades.
• Documentación de Anthropic relacionada:
  • Adaptive thinking
  • Extended thinking

Fast mode (Anthropic API)

El interruptor compartido /fast de OpenClaw también admite tráfico directo público de Anthropic. Esto incluye peticiones con API key y autenticación OAuth enviadas a api.anthropic.com.

• Los comandos /fast on y /fast off mapean a service_tier: "auto" y service_tier: "standard_only" respectivamente.
• Configuración por defecto:

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-sonnet-4-6": {
          params: { fastMode: true },
        },
      },
    },
  },
}

Límites importantes:

• OpenClaw solo inyecta los niveles de servicio de Anthropic para peticiones directas a api.anthropic.com. Si envías anthropic/* a través de un proxy o Gateway, /fast no modificará el service_tier.
• Los parámetros de modelo explícitos de Anthropic serviceTier o service_tier tienen prioridad sobre el valor por defecto de /fast cuando ambos están configurados.
• Anthropic indica el nivel efectivo en la respuesta dentro de usage.service_tier. En cuentas sin capacidad de Priority Tier, service_tier: "auto" podría resolverse como standard.

Prompt caching (Anthropic API)

OpenClaw soporta la función de prompt caching de Anthropic. Esto es exclusivo para la API; la autenticación por suscripción no respeta los ajustes de caché.

Configuración

Usa el parámetro cacheRetention en la configuración de tu modelo:

Valor	Duración de Caché	Descripción
none	Sin caché	Desactiva el prompt caching
short	5 minutos	Por defecto para auth con API Key
long	1 hora	Caché extendido (requiere beta flag)

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": {
          params: { cacheRetention: "long" },
        },
      },
    },
  },
}

Valores por defecto

Al usar la autenticación por Anthropic API Key, OpenClaw aplica automáticamente cacheRetention: "short" (caché de 5 minutos) para todos los modelos de Anthropic. Puedes cambiar esto configurando cacheRetention de forma explícita en tu configuración.

Sobrescritura de cacheRetention por agente

Usa los parámetros a nivel de modelo como base y luego define excepciones para agentes específicos mediante agents.list[].params.

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-6" },
      models: {
        "anthropic/claude-opus-4-6": {
          params: { cacheRetention: "long" }, // baseline for most agents
        },
      },
    },
    list: [
      { id: "research", default: true },
      { id: "alerts", params: { cacheRetention: "none" } }, // override for this agent only
    ],
  },
}

Orden de prioridad para parámetros de caché:

1. agents.defaults.models["provider/model"].params
2. agents.list[].params (si coincide el id, sobrescribe por clave)

Esto permite que un agente mantenga una caché de larga duración mientras otro agente con el mismo modelo la desactiva para evitar costes de escritura en tráfico con poca reutilización.

Notas sobre Bedrock Claude

• Los modelos Anthropic Claude en Bedrock (amazon-bedrock/*anthropic.claude*) aceptan el paso de cacheRetention si se configuran.
• Los modelos de Bedrock que no son de Anthropic se fuerzan a cacheRetention: "none" en tiempo de ejecución.
• Los valores inteligentes por defecto de la API key de Anthropic también aplican cacheRetention: "short" para referencias de modelos Claude-on-Bedrock si no hay un valor explícito.

Parámetro antiguo (Legacy)

El parámetro anterior cacheControlTtl sigue funcionando por compatibilidad:

• "5m" equivale a short
• "1h" equivale a long

Te recomendamos migrar al nuevo parámetro cacheRetention.

OpenClaw incluye el flag beta extended-cache-ttl-2025-04-11 para peticiones a la API de Anthropic; mantenlo si vas a sobrescribir los headers del proveedor (consulta /gateway/configuration).

Ventana de contexto de 1M (Anthropic beta)

La ventana de contexto de 1M de Anthropic está en fase beta. En OpenClaw, puedes activarla por modelo con params.context1m: true para los modelos Opus/Sonnet compatibles.

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": {
          params: { context1m: true },
        },
      },
    },
  },
}

OpenClaw traduce esto a anthropic-beta: context-1m-2025-08-07 en las peticiones a Anthropic. Esto solo se activa si params.context1m se marca explícitamente como true para ese modelo.

Requisito: Anthropic debe permitir el uso de contexto largo en esa credencial (normalmente facturación por API key o una cuenta de suscripción con Extra Usage activado). De lo contrario, Anthropic devolverá: HTTP 429: rate_limit_error: Extra usage is required for long context requests.

Nota: Actualmente Anthropic rechaza las peticiones beta context-1m-* si usas setup-tokens de suscripción (sk-ant-oat-*). Si configuras context1m: true con autenticación de suscripción, OpenClaw mostrará un aviso y usará la ventana de contexto estándar, omitiendo el header beta de 1M pero manteniendo los betas de OAuth necesarios.

Opción B: Claude CLI como proveedor de mensajes

Ideal para: un host de Gateway para un solo usuario que ya tiene Claude CLI instalado y con una sesión iniciada de suscripción a Claude.

Este camino usa el binario local de claude para la inferencia del modelo en lugar de llamar directamente a la API de Anthropic. OpenClaw lo trata como un CLI backend provider con referencias de modelo como:

• claude-cli/claude-sonnet-4-6
• claude-cli/claude-opus-4-6

Cómo funciona:

1. OpenClaw ejecuta claude -p --output-format json ... en el host del Gateway.
2. El primer turno envía --session-id <uuid>.
3. Los turnos siguientes reutilizan la sesión de Claude guardada mediante --resume <sessionId>.
4. Tus mensajes del chat siguen el flujo normal de OpenClaw, pero la respuesta del modelo la genera Claude CLI.

Requisitos

• Claude CLI instalado en el host del Gateway (disponible en el PATH o con ruta absoluta) y ya autenticado en ese mismo host.
• OpenClaw carga automáticamente el plugin de Anthropic al iniciar el Gateway si tu configuración referencia claude-cli/... o la configuración del backend claude-cli.

claude auth status

Snippet de configuración

{
  agents: {
    defaults: {
      model: {
        primary: "claude-cli/claude-sonnet-4-6",
      },
      models: {
        "claude-cli/claude-sonnet-4-6": {},
      },
      sandbox: { mode: "off" },
    },
  },
}

Si el binario claude no está en el PATH del host del Gateway:

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
      },
    },
  },
}

Qué obtienes

• Reutilización de la autenticación de suscripción de Claude desde la CLI local y continuidad de la sesión entre turnos.
• Enrutamiento estándar de mensajes y sesiones a través de OpenClaw.

Migrar de autenticación de Anthropic a Claude CLI

Si usas anthropic/... con un setup-token o API key y quieres cambiar el host del Gateway a Claude CLI:

openclaw models auth login --provider anthropic --method cli --set-default

O durante el onboarding:

openclaw onboard --auth-choice anthropic-cli

Qué hace este proceso:

• Verifica que Claude CLI ya tenga la sesión iniciada en el host del Gateway.
• Cambia el modelo por defecto a claude-cli/....
• Reescribe los fallbacks de modelos de Anthropic como anthropic/claude-opus-4-6 a claude-cli/claude-opus-4-6.
• Añade las entradas de claude-cli/... correspondientes en agents.defaults.models.

Qué no hace:

• No borra tus perfiles de autenticación de Anthropic existentes.
• No elimina referencias antiguas de anthropic/... fuera de la ruta principal de modelos permitidos.

Esto hace que volver atrás sea sencillo: solo tienes que cambiar el modelo por defecto a anthropic/... si lo necesitas.

Límites importantes

• Este no es el proveedor de la API de Anthropic. Es el entorno de ejecución de la CLI local.
• Las herramientas (tools) están desactivadas en OpenClaw para las ejecuciones del backend de la CLI.
• Entrada de texto, salida de texto. No hay transferencia de streaming en OpenClaw.
• Es mejor para un host de Gateway personal, no para configuraciones multiusuario con facturación compartida.

Más detalles en: /gateway/cli-backends

Opción C: Claude setup-token

Ideal para: usar tu suscripción de Claude.

Dónde conseguir un setup-token

Los setup-tokens se crean con la Claude Code CLI, no en la Anthropic Console. Puedes ejecutar esto en cualquier máquina:

claude setup-token

Pega el token en OpenClaw (asistente: Anthropic token (paste setup-token)), o ejecútalo en el host del Gateway:

openclaw models auth setup-token --provider anthropic

Si generaste el token en una máquina diferente, pégalo:

openclaw models auth paste-token --provider anthropic

Configuración de la CLI (setup-token)

# Paste a setup-token during setup
openclaw onboard --auth-choice setup-token

Snippet de configuración (setup-token)

{
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}

Notas

• Genera el setup-token con claude setup-token y pégalo, o ejecuta openclaw models auth setup-token en el host del Gateway.
• Si ves el error “OAuth token refresh failed …” en una suscripción de Claude, vuelve a autenticarte con un setup-token. Consulta /gateway/troubleshooting.
• Los detalles de autenticación y reglas de reutilización están en /concepts/oauth.
• Revisa la sección de solución de problemas si encuentras errores inesperados durante la configuración.

Solución de problemas (Troubleshooting)

Errores 401 / token inválido de repente

• La autenticación de la suscripción de Claude puede caducar o ser revocada. Ejecuta de nuevo claude setup-token y pégalo en el host del Gateway.
• Si el login de Claude CLI está en otra máquina, usa openclaw models auth paste-token --provider anthropic en el host del Gateway.

No API key found for provider “anthropic”

• La autenticación es por agente. Los nuevos agentes no heredan las llaves del agente principal.
• Ejecuta de nuevo el onboarding para ese agente, o pega un setup-token / API key en el host del Gateway y verifica con openclaw models status.

No credentials found for profile anthropic:default

• Ejecuta openclaw models status para ver qué perfil de autenticación está activo.
• Repite el onboarding o pega un setup-token / API key para ese perfil.

No available auth profile (all in cooldown/unavailable)

• Revisa openclaw models status --json para ver auth.unusableProfiles.
• Añade otro perfil de Anthropic o espera a que termine el tiempo de espera.

Más información: /gateway/troubleshooting y /help/faq.

Próximos pasos

• /gateway/configuration
• /concepts/oauth

AI Setup Assistant