Herramientas (OpenClaw)

OpenClaw expone herramientas de agente de primera clase para browser, canvas, nodes y cron. Estas reemplazan los antiguos skills openclaw-*: las herramientas son tipadas, sin necesidad de shell, y el agente debe usarlas directamente.

Desactivar herramientas

Puedes permitir o denegar herramientas globalmente mediante tools.allow / tools.deny en openclaw.json (deny tiene prioridad). Esto evita que las herramientas no permitidas se envíen a los proveedores de modelos.

{
  tools: { deny: ["browser"] },
}

Notas:

  • La coincidencia no distingue mayúsculas de minúsculas.
  • Se admiten comodines * ("*" significa todas las herramientas).
  • Si tools.allow solo referencia nombres de herramientas de plugins desconocidos o no cargados, OpenClaw registra una advertencia e ignora la lista blanca para que las herramientas principales sigan disponibles.

Perfiles de herramientas (lista base de permitidos)

tools.profile establece una lista base de herramientas permitidas antes de tools.allow/tools.deny. Sobreescritura por agente: agents.list[].tools.profile.

Perfiles:

  • minimal: solo session_status
  • coding: group:fs, group:runtime, group:sessions, group:memory, image
  • messaging: group:messaging, sessions_list, sessions_history, sessions_send, session_status
  • full: sin restricciones (equivalente a no configurar)

Ejemplo (solo mensajería por defecto, permitir también herramientas de Slack + Discord):

{
  tools: {
    profile: "messaging",
    allow: ["slack", "discord"],
  },
}

Ejemplo (perfil coding, pero denegar exec/process en todas partes):

{
  tools: {
    profile: "coding",
    deny: ["group:runtime"],
  },
}

Ejemplo (perfil coding global, agente de soporte solo mensajería):

{
  tools: { profile: "coding" },
  agents: {
    list: [
      {
        id: "support",
        tools: { profile: "messaging", allow: ["slack"] },
      },
    ],
  },
}

Política de herramientas por proveedor

Usa tools.byProvider para restringir aún más las herramientas para proveedores específicos (o un solo provider/model) sin cambiar tus valores globales predeterminados. Sobreescritura por agente: agents.list[].tools.byProvider.

Se aplica después del perfil base de herramientas y antes de las listas allow/deny, por lo que solo puede reducir el conjunto de herramientas. Las claves de proveedor aceptan tanto provider (ej. google-antigravity) como provider/model (ej. openai/gpt-5.2).

Ejemplo (mantener perfil coding global, pero herramientas mínimas para Google Antigravity):

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
    },
  },
}

Ejemplo (lista de permitidos específica por provider/model para un endpoint inestable):

{
  tools: {
    allow: ["group:fs", "group:runtime", "sessions_list"],
    byProvider: {
      "openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] },
    },
  },
}

Ejemplo (sobreescritura por agente para un solo proveedor):

{
  agents: {
    list: [
      {
        id: "support",
        tools: {
          byProvider: {
            "google-antigravity": { allow: ["message", "sessions_list"] },
          },
        },
      },
    ],
  },
}

Grupos de herramientas (atajos)

Las políticas de herramientas (global, agente, sandbox) admiten entradas group:* que se expanden a múltiples herramientas. Úsalas en tools.allow / tools.deny.

Grupos disponibles:

  • group:runtime: exec, bash, process
  • group:fs: read, write, edit, apply_patch
  • group:sessions: sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
  • group:memory: memory_search, memory_get
  • group:web: web_search, web_fetch
  • group:ui: browser, canvas
  • group:automation: cron, gateway
  • group:messaging: message
  • group:nodes: nodes
  • group:openclaw: todas las herramientas integradas de OpenClaw (excluye plugins de proveedor)

Ejemplo (permitir solo herramientas de archivos + browser):

{
  tools: {
    allow: ["group:fs", "browser"],
  },
}

Plugins + herramientas

Los plugins pueden registrar herramientas adicionales (y comandos CLI) más allá del conjunto base. Consulta Plugins para instalación y configuración, y Skills para entender cómo las guías de uso de herramientas se inyectan en los prompts. Algunos plugins incluyen sus propios skills junto con las herramientas (por ejemplo, el plugin de llamadas de voz).

Herramientas opcionales de plugins:

  • Lobster: runtime tipado de workflows con aprobaciones reanudables (requiere el CLI de Lobster en el host del gateway).
  • LLM Task: paso LLM solo JSON para salida estructurada de workflows (validación de esquema opcional).
  • Diffs: visor de diffs de solo lectura y renderizador de archivos PNG o PDF para texto antes/después o parches unificados.

Inventario de herramientas

apply_patch

Aplica parches estructurados en uno o más archivos. Úsalo para ediciones con múltiples bloques. Experimental: actívalo con tools.exec.applyPatch.enabled (solo modelos OpenAI). tools.exec.applyPatch.workspaceOnly tiene por defecto true (contenido al workspace). Ponlo en false solo si deseas intencionalmente que apply_patch escriba/elimine fuera del directorio del workspace.

exec

Ejecuta comandos de shell en el workspace.

Parámetros principales:

  • command (obligatorio)
  • yieldMs (pasa a segundo plano automáticamente tras el timeout, por defecto 10000)
  • background (segundo plano inmediato)
  • timeout (segundos; mata el proceso si se excede, por defecto 1800)
  • elevated (bool; ejecuta en el host si el modo elevado está habilitado/permitido; solo cambia el comportamiento cuando el agente está en sandbox)
  • host (sandbox | gateway | node)
  • security (deny | allowlist | full)
  • ask (off | on-miss | always)
  • node (id/nombre del nodo para host=node)
  • ¿Necesitas un TTY real? Configura pty: true.

Notas:

  • Devuelve status: "running" con un sessionId cuando pasa a segundo plano.
  • Usa process para consultar/registrar/escribir/matar/limpiar sesiones en segundo plano.
  • Si process no está permitido, exec se ejecuta de forma síncrona e ignora yieldMs/background.
  • elevated está controlado por tools.elevated más cualquier sobreescritura agents.list[].tools.elevated (ambas deben permitirlo) y es un alias para host=gateway + security=full.
  • elevated solo cambia el comportamiento cuando el agente está en sandbox (en caso contrario no tiene efecto).
  • host=node puede apuntar a una app companion de macOS o a un host de nodo headless (openclaw node run).
  • Aprobaciones y listas de permitidos de gateway/node: Aprobaciones de Exec.

process

Gestiona sesiones de exec en segundo plano.

Acciones principales:

  • list, poll, log, write, kill, clear, remove

Notas:

  • poll devuelve la nueva salida y el estado de salida cuando se completa.
  • log admite offset/limit basados en líneas (omite offset para obtener las últimas N líneas).
  • process tiene alcance por agente; las sesiones de otros agentes no son visibles.

loop-detection (protecciones contra bucles de llamadas a herramientas)

OpenClaw rastrea el historial reciente de llamadas a herramientas y bloquea o advierte cuando detecta bucles repetitivos sin progreso. Actívalo con tools.loopDetection.enabled: true (por defecto es false).

{
  tools: {
    loopDetection: {
      enabled: true,
      warningThreshold: 10,
      criticalThreshold: 20,
      globalCircuitBreakerThreshold: 30,
      historySize: 30,
      detectors: {
        genericRepeat: true,
        knownPollNoProgress: true,
        pingPong: true,
      },
    },
  },
}
  • genericRepeat: patrón repetido de la misma herramienta + mismos parámetros.
  • knownPollNoProgress: herramientas tipo polling repetidas con salidas idénticas.
  • pingPong: patrones alternantes A/B/A/B sin progreso.
  • Sobreescritura por agente: agents.list[].tools.loopDetection.

Busca en la web usando Perplexity, Brave, Gemini, Grok o Kimi.

Parámetros principales:

  • query (obligatorio)
  • count (1-10; por defecto desde tools.web.search.maxResults)

Notas:

  • Requiere una clave API para el proveedor elegido (recomendado: openclaw configure --section web).
  • Actívalo con tools.web.search.enabled.
  • Las respuestas se almacenan en caché (15 min por defecto).
  • Consulta Herramientas web para la configuración.

web_fetch

Obtiene y extrae contenido legible de una URL (HTML -> markdown/texto).

Parámetros principales:

  • url (obligatorio)
  • extractMode (markdown | text)
  • maxChars (trunca páginas largas)

Notas:

  • Actívalo con tools.web.fetch.enabled.
  • maxChars está limitado por tools.web.fetch.maxCharsCap (por defecto 50000).
  • Las respuestas se almacenan en caché (15 min por defecto).
  • Para sitios con mucho JS, prefiere la herramienta browser.
  • Consulta Herramientas web para la configuración.
  • Consulta Firecrawl para el fallback anti-bot opcional.

browser

Controla el navegador dedicado gestionado por OpenClaw.

Acciones principales:

  • status, start, stop, tabs, open, focus, close
  • snapshot (aria/ai)
  • screenshot (devuelve bloque de imagen + MEDIA:<path>)
  • act (acciones de UI: click/type/press/hover/drag/select/fill/resize/wait/evaluate)
  • navigate, console, pdf, upload, dialog

Gestión de perfiles:

  • profiles — listar todos los perfiles del navegador con estado
  • create-profile — crear nuevo perfil con puerto asignado automáticamente (o cdpUrl)
  • delete-profile — detener navegador, eliminar datos de usuario, quitar de la configuración (solo local)
  • reset-profile — matar proceso huérfano en el puerto del perfil (solo local)

Parámetros comunes:

  • profile (opcional; por defecto browser.defaultProfile)
  • target (sandbox | host | node)
  • node (opcional; elige un id/nombre de nodo específico) Notas:
  • Requiere browser.enabled=true (por defecto es true; ponlo en false para desactivar).
  • Todas las acciones aceptan el parámetro opcional profile para soporte multi-instancia.
  • Cuando se omite profile, usa browser.defaultProfile (por defecto “chrome”).
  • Nombres de perfil: solo alfanuméricos en minúsculas + guiones (máx. 64 caracteres).
  • Rango de puertos: 18800-18899 (~100 perfiles máx.).
  • Los perfiles remotos son solo para conexión (sin start/stop/reset).
  • Si hay un nodo con capacidad de navegador conectado, la herramienta puede enrutar automáticamente hacia él (a menos que fijes target).
  • snapshot usa ai por defecto cuando Playwright está instalado; usa aria para el árbol de accesibilidad.
  • snapshot también admite opciones de snapshot por rol (interactive, compact, depth, selector) que devuelven refs como e12.
  • act requiere ref de snapshot (12 numérico de snapshots AI, o e12 de snapshots por rol); usa evaluate para necesidades específicas de selectores CSS.
  • Evita act -> wait por defecto; úsalo solo en casos excepcionales (sin estado de UI confiable para esperar).
  • upload puede opcionalmente pasar un ref para hacer auto-click después de activar.
  • upload también admite inputRef (ref aria) o element (selector CSS) para establecer <input type="file"> directamente.

canvas

Controla el Canvas del nodo (present, eval, snapshot, A2UI).

Acciones principales:

  • present, hide, navigate, eval
  • snapshot (devuelve bloque de imagen + MEDIA:<path>)
  • a2ui_push, a2ui_reset

Notas:

  • Usa node.invoke del gateway internamente.
  • Si no se proporciona node, la herramienta elige uno por defecto (nodo único conectado o nodo mac local).
  • A2UI es solo v0.8 (sin createSurface); el CLI rechaza JSONL v0.9 con errores de línea.
  • Prueba rápida: openclaw nodes canvas a2ui push --node <id> --text "Hello from A2UI".

nodes

Descubre y apunta a nodos emparejados; envía notificaciones; captura cámara/pantalla.

Acciones principales:

  • status, describe
  • pending, approve, reject (emparejamiento)
  • notify (macOS system.notify)
  • run (macOS system.run)
  • camera_list, camera_snap, camera_clip, screen_record
  • location_get, notifications_list, notifications_action
  • device_status, device_info, device_permissions, device_health

Notas:

  • Los comandos de cámara/pantalla requieren que la app del nodo esté en primer plano.
  • Las imágenes devuelven bloques de imagen + MEDIA:<path>.
  • Los videos devuelven FILE:<path> (mp4).
  • La ubicación devuelve un payload JSON (lat/lon/accuracy/timestamp).
  • Parámetros de run: array command argv; opcionales cwd, env (KEY=VAL), commandTimeoutMs, invokeTimeoutMs, needsScreenRecording.

Ejemplo (run):

{
  "action": "run",
  "node": "office-mac",
  "command": ["echo", "Hello"],
  "env": ["FOO=bar"],
  "commandTimeoutMs": 12000,
  "invokeTimeoutMs": 45000,
  "needsScreenRecording": false
}

image

Analiza una imagen con el modelo de imagen configurado.

Parámetros principales:

  • image (ruta o URL obligatoria)
  • prompt (opcional; por defecto “Describe the image.”)
  • model (sobreescritura opcional)
  • maxBytesMb (límite de tamaño opcional)

Notas:

  • Solo disponible cuando agents.defaults.imageModel está configurado (primario o fallbacks), o cuando se puede inferir un modelo de imagen implícito desde tu modelo predeterminado + autenticación configurada (emparejamiento best-effort).
  • Usa el modelo de imagen directamente (independiente del modelo de chat principal).

pdf

Analiza uno o más documentos PDF.

Para el comportamiento completo, límites, configuración y ejemplos, consulta Herramienta PDF.

message

Envía mensajes y acciones de canal a través de Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/iMessage/MS Teams.

Acciones principales:

  • send (texto + media opcional; MS Teams también admite card para Adaptive Cards)
  • poll (encuestas de WhatsApp/Discord/MS Teams)
  • react / reactions / read / edit / delete
  • pin / unpin / list-pins
  • permissions
  • thread-create / thread-list / thread-reply
  • search
  • sticker
  • member-info / role-info
  • emoji-list / emoji-upload / sticker-upload
  • role-add / role-remove
  • channel-info / channel-list
  • voice-status
  • event-list / event-create
  • timeout / kick / ban

Notas:

  • send enruta WhatsApp a través del Gateway; los demás canales van directo.
  • poll usa el Gateway para WhatsApp y MS Teams; las encuestas de Discord van directo.
  • Cuando una llamada a la herramienta message está vinculada a una sesión de chat activa, los envíos se restringen al destino de esa sesión para evitar filtraciones entre contextos.

cron

Gestiona trabajos cron del Gateway y despertares.

Acciones principales:

  • status, list
  • add, update, remove, run, runs
  • wake (encola evento del sistema + latido inmediato opcional)

Notas:

  • add espera un objeto completo de trabajo cron (mismo esquema que cron.add RPC).
  • update usa { jobId, patch } (id aceptado por compatibilidad).

gateway

Reinicia o aplica actualizaciones al proceso del Gateway en ejecución (in-place).

Acciones principales:

  • restart (autoriza + envía SIGUSR1 para reinicio en proceso; openclaw gateway reinicio in-place)
  • config.schema.lookup (inspecciona una ruta de configuración a la vez sin cargar el esquema completo en el contexto del prompt)
  • config.get
  • config.apply (validar + escribir config + reiniciar + despertar)
  • config.patch (merge de actualización parcial + reiniciar + despertar)
  • update.run (ejecutar actualización + reiniciar + despertar)

Notas:

  • config.schema.lookup espera una ruta de configuración específica como gateway.auth o agents.list.*.heartbeat.
  • Las rutas pueden incluir ids de plugins delimitados por barra cuando se direccionan plugins.entries.<id>, por ejemplo plugins.entries.pack/one.config.
  • Usa delayMs (por defecto 2000) para evitar interrumpir una respuesta en curso.
  • config.schema sigue disponible para flujos internos de la UI de Control y no se expone a través de la herramienta de agente gateway.
  • restart está habilitado por defecto; configura commands.restart: false para desactivarlo.

sessions_list / sessions_history / sessions_send / sessions_spawn / session_status

Lista sesiones, inspecciona el historial de transcripciones o envía a otra sesión.

Parámetros principales:

  • sessions_list: kinds?, limit?, activeMinutes?, messageLimit? (0 = ninguno)
  • sessions_history: sessionKey (o sessionId), limit?, includeTools?
  • sessions_send: sessionKey (o sessionId), message, timeoutSeconds? (0 = fire-and-forget)
  • sessions_spawn: task, label?, runtime?, agentId?, model?, thinking?, cwd?, runTimeoutSeconds?, thread?, mode?, cleanup?, sandbox?, streamTo?, attachments?, attachAs?
  • session_status: sessionKey? (por defecto la actual; acepta sessionId), model? (default limpia la sobreescritura)

Notas:

  • main es la clave canónica de chat directo; global/unknown están ocultos.
  • messageLimit > 0 obtiene los últimos N mensajes por sesión (mensajes de herramientas filtrados).
  • El direccionamiento de sesiones se controla con tools.sessions.visibility (por defecto tree: sesión actual + sesiones de subagentes generados). Si ejecutas un agente compartido para múltiples usuarios, considera configurar tools.sessions.visibility: "self" para evitar navegación entre sesiones.
  • sessions_send espera la finalización cuando timeoutSeconds > 0.
  • La entrega/anuncio ocurre después de la finalización y es best-effort; status: "ok" confirma que la ejecución del agente terminó, no que el anuncio fue entregado.
  • sessions_spawn admite runtime: "subagent" | "acp" (subagent por defecto). Para el comportamiento del runtime ACP, consulta Agentes ACP.
  • Para runtime ACP, streamTo: "parent" enruta los resúmenes de progreso de la ejecución inicial de vuelta a la sesión solicitante como eventos del sistema en lugar de entrega directa al hijo.
  • sessions_spawn inicia una ejecución de sub-agente y publica una respuesta de anuncio de vuelta al chat solicitante.
    • Admite modo one-shot (mode: "run") y modo persistente vinculado a hilo (mode: "session" con thread: true).
    • Si thread: true y se omite mode, el modo por defecto es session.
    • mode: "session" requiere thread: true.
    • Si se omite runTimeoutSeconds, OpenClaw usa agents.defaults.subagents.runTimeoutSeconds cuando está configurado; de lo contrario el timeout por defecto es 0 (sin timeout).
    • Los flujos vinculados a hilos de Discord dependen de session.threadBindings.* y channels.discord.threadBindings.*.
    • El formato de respuesta incluye Status, Result y estadísticas compactas.
    • Result es el texto de completado del asistente; si falta, se usa el último toolResult como fallback.
  • Los spawns en modo de completado manual envían directamente primero, con fallback a cola y reintento en fallos transitorios (status: "ok" significa que la ejecución terminó, no que el anuncio fue entregado).
  • sessions_spawn admite adjuntos de archivos inline solo para runtime de subagente (ACP los rechaza). Cada adjunto tiene name, content, y opcionalmente encoding (utf8 o base64) y mimeType. Los archivos se materializan en el workspace hijo en .openclaw/attachments/<uuid>/ con un archivo de metadatos .manifest.json. La herramienta devuelve un recibo con count, totalBytes, sha256 por archivo y relDir. El contenido de los adjuntos se redacta automáticamente de la persistencia de transcripciones.
    • Configura límites con tools.sessions_spawn.attachments (enabled, maxTotalBytes, maxFiles, maxFileBytes, retainOnSessionKeep).
    • attachAs.mountPath es una indicación reservada para futuras implementaciones de montaje.
  • sessions_spawn es no bloqueante y devuelve status: "accepted" inmediatamente.
  • Las respuestas ACP streamTo: "parent" pueden incluir streamLogPath (*.acp-stream.jsonl con alcance de sesión) para seguir el historial de progreso.
  • sessions_send ejecuta un ping-pong de respuesta (responde REPLY_SKIP para detener; turnos máx. con session.agentToAgent.maxPingPongTurns, 0-5).
  • Después del ping-pong, el agente destino ejecuta un paso de anuncio; responde ANNOUNCE_SKIP para suprimir el anuncio.
  • Restricción de sandbox: cuando la sesión actual está en sandbox y agents.defaults.sandbox.sessionToolsVisibility: "spawned", OpenClaw fija tools.sessions.visibility a tree.

agents_list

Lista los ids de agentes que la sesión actual puede apuntar con sessions_spawn.

Notas:

  • El resultado está restringido a las listas de permitidos por agente (agents.list[].subagents.allowAgents).
  • Cuando se configura ["*"], la herramienta incluye todos los agentes configurados y marca allowAny: true.

Parámetros (comunes)

Herramientas respaldadas por el Gateway (canvas, nodes, cron):

  • gatewayUrl (por defecto ws://127.0.0.1:18789)
  • gatewayToken (si la autenticación está habilitada)
  • timeoutMs

Nota: cuando gatewayUrl está configurado, incluye gatewayToken explícitamente. Las herramientas no heredan credenciales de configuración o entorno para sobreescrituras, y la falta de credenciales explícitas es un error.

Herramienta browser:

Flujos de agente recomendados

Automatización del navegador:

  1. browser -> status / start
  2. snapshot (ai o aria)
  3. act (click/type/press)
  4. screenshot si necesitas confirmación visual

Renderizado del canvas:

  1. canvas -> present
  2. a2ui_push (opcional)
  3. snapshot

Direccionamiento de nodos:

  1. nodes -> status
  2. describe en el nodo elegido
  3. notify / run / camera_snap / screen_record

Seguridad

  • Evita system.run directo; usa nodes -> run solo con consentimiento explícito del usuario.
  • Respeta el consentimiento del usuario para capturas de cámara/pantalla.
  • Usa status/describe para asegurar los permisos antes de invocar comandos multimedia.

Cómo se presentan las herramientas al agente

Las herramientas se exponen en dos canales paralelos:

  1. Texto del prompt del sistema: una lista legible + guía.
  2. Esquema de herramientas: las definiciones de funciones estructuradas enviadas a la API del modelo.

Esto significa que el agente ve tanto “qué herramientas existen” como “cómo llamarlas.” Si una herramienta no aparece en el prompt del sistema ni en el esquema, el modelo no puede llamarla.

arrow_back
Anterior
Queue
Siguiente
Apply Patch
arrow_forward