Configuración de Herramientas en OpenClaw

Gestionar los permisos de los agentes suele ser un dolor de cabeza. Quieres que tus agentes sean útiles, pero no quieres que accedan a todo a la vez o que ejecuten comandos que no deberían. Es difícil encontrar un equilibrio entre darles suficiente poder para trabajar y mantener el entorno seguro.

OpenClaw soluciona esto con herramientas de primer nivel para el browser, canvas, nodes y cron. Estas herramientas reemplazan a las antiguas skills de openclaw-*: ahora están tipadas, no requieren shelling y el agente puede usarlas directamente.

Requisitos previos

• Archivo de configuración openclaw.json.
• Herramientas de OpenClaw cargadas (browser, canvas, nodes o cron).

Inicio rápido

Puedes permitir o denegar herramientas de forma global usando tools.allow y tools.deny en tu archivo openclaw.json. Si hay un conflicto, la regla de denegar siempre gana. Esto evita que las herramientas no permitidas se envíen a los model providers.

Para desactivar el browser globalmente, añade esto a tu configuración:

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

Ten en cuenta estos detalles:

• La coincidencia de nombres no distingue entre mayúsculas y minúsculas.
• Puedes usar el comodín * para afectar a todas las herramientas (por ejemplo, "*").

Perfiles de herramientas

Si no quieres configurar cada herramienta una por una, usa tools.profile. Esto define una lista base de permisos antes de aplicar tus reglas manuales de allow o deny.

Estos son los perfiles disponibles:

• minimal: Solo incluye session_status.
• coding: Incluye group:fs, group:runtime, group:sessions, group:memory e image.
• messaging: Incluye group:messaging, sessions_list, sessions_history, sessions_send y session_status.
• full: Sin restricciones (es el valor por defecto).

Ejemplos de configuración

Si quieres usar el perfil de mensajería pero también necesitas soporte para Slack y Discord, configura tu openclaw.json así:

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

También puedes denegar grupos específicos dentro de un perfil. Aquí usas el perfil de programación pero bloqueas la ejecución de procesos:

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

Sobrescribir perfiles por agente

Puedes definir un perfil global y cambiarlo para un agente específico usando agents.list[].tools.profile. En este ejemplo, el agente de soporte solo usa mensajería y Slack, aunque el perfil global sea para programación:

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

Solución de problemas

OpenClaw ignora mi allowlist y muestra un aviso Si tools.allow solo contiene nombres de herramientas de plugins desconocidos o que no se han cargado, OpenClaw registrará un aviso en los logs. En este caso, el sistema ignorará tu lista para asegurar que las herramientas principales (core tools) sigan disponibles.

Para resolver dudas específicas sobre tu configuración, usa el AI Setup Assistant.

Próximos pasos

• Configuración de Agentes
• Uso del Gateway
• API Reference
• Guía de Node.js

¿Alguna vez has sentido que un modelo se confunde cuando tiene demasiadas herramientas a su disposición? Gestionar permisos de forma global puede ser un problema cuando un provider específico no procesa bien ciertas funciones o cuando quieres limitar el acceso para controlar mejor el comportamiento de cada modelo.

Aquí tienes cómo puedes ajustar el conjunto de herramientas de forma granular para que cada modelo reciba exactamente lo que necesita.

Requisitos previos

• Configuración de tools definida en tu entorno.
• Lista de agents configurada (si necesitas overrides por agente).

Inicio rápido

Usa tools.byProvider para restringir aún más las herramientas de providers específicos (o un par provider/model único) sin cambiar tus valores globales predeterminados. Si necesitas un ajuste por agente, usa agents.list[].tools.byProvider.

Esta política se aplica después del perfil de herramientas base y antes de las listas allow/deny. Por lo tanto, solo sirve para reducir o estrechar el conjunto de herramientas disponible. Las claves aceptan el provider (ej. google-antigravity) o el provider/model (ej. openai/gpt-5.2).

Ejemplo: Perfil mínimo para un provider específico

Si quieres mantener tu perfil de “coding” global, pero prefieres herramientas mínimas cuando uses Google Antigravity:

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

Ejemplo: Allowlist para un endpoint inestable

Si notas que un modelo específico falla con ciertas herramientas, puedes definir una allowlist exclusiva para ese provider/model:

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

Ejemplo: Override en un agente

También puedes aplicar estas restricciones dentro de la configuración de un agente específico:

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

Solución de problemas

¿Tienes un endpoint inestable (flaky endpoint)? Si un modelo o provider específico presenta errores al intentar usar ciertas herramientas, utiliza byProvider para limitar su acceso únicamente a las funciones que maneja con éxito. Esto evita fallos en la ejecución sin tener que modificar los permisos de los modelos que sí funcionan correctamente.

¿Necesitas ayuda para configurar tus herramientas? Prueba nuestro AI Setup Assistant.

Próximos pasos

• Configuración de Agents
• Perfiles de Tools

Configurar permisos herramienta por herramienta puede volverse un caos rápidamente. Si alguna vez has sentido que tu archivo de configuración es una lista interminable de permisos individuales solo para dar acceso básico al sistema de archivos o al navegador, los Tool groups son la solución. Recomiendo usar estos shorthands para mantener tus políticas limpias y fáciles de mantener.

Requisitos previos

• Acceso a la configuración de Tool policies (global, agent o sandbox).
• Uso de los campos tools.allow o tools.deny.

Inicio rápido

Las Tool groups te permiten usar la sintaxis group:* para habilitar múltiples herramientas relacionadas de un solo golpe. Aquí tienes los grupos disponibles que puedes integrar ahora mismo:

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

Si quieres permitir únicamente las herramientas de archivos y el navegador, usa este ejemplo en tu configuración:

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

Plugins + tools

Los plugins pueden registrar herramientas adicionales y comandos de CLI que van más allá del conjunto core. Puedes revisar Plugins para la instalación y configuración, y Skills para entender cómo se inyecta la guía de uso de herramientas en los prompts. Algunos plugins, como el de voice-call, envían sus propias skills junto con las herramientas.

Herramientas de plugins opcionales:

• Lobster: runtime de workflow tipado con aprobaciones reanudables.
• LLM Task: paso de LLM exclusivo para JSON para obtener salidas de workflow estructuradas.

Solución de problemas

• Lobster no funciona: Recuerda que la herramienta Lobster requiere que tengas instalado el Lobster CLI en el host del Gateway.
• Herramientas de terceros ausentes: Ten en cuenta que group:openclaw solo cubre las herramientas nativas. Si usas plugins de proveedores externos, tendrás que habilitarlos por separado.

¿Necesitas ayuda configurando tus grupos de herramientas? Prueba nuestro AI Setup Assistant.

Próximos pasos

• Plugins
• Skills

---
title: "Tool inventory: Maximiza las capacidades de tu agente"
description: "Guía detallada sobre el inventario de herramientas de OpenClaw para ejecución de comandos, navegación web y gestión de nodos."
---

¿Alguna vez has sentido que pierdes el ritmo saltando entre la terminal, el navegador y tu editor de código mientras intentas que tu agente haga algo útil? Es frustrante tener que configurar cada pequeña interacción manualmente cuando lo único que quieres es que el modelo interactúe con el mundo real de forma directa.

Tener un agente que solo "habla" es limitar su potencial. Para que un flujo de trabajo sea realmente efectivo, tu agente necesita manos: capacidad para ejecutar código, navegar por la web y comunicarse por diferentes canales sin que tengas que intervenir en cada paso.

## Requisitos previos

Para usar estas herramientas, asegúrate de cumplir con lo siguiente:

*   OpenClaw instalado y el Gateway en ejecución.
*   Modelos de IA configurados con soporte para Tool Calling.
*   Claves de API necesarias (como Brave API para búsquedas).
*   Permisos de ejecución en tu entorno de trabajo.

## Inicio rápido

Si quieres ver las herramientas en acción en menos de 5 minutos, sigue estos pasos:

1.  **Habilita la ejecución**: En tu configuración, asegúrate de que `tools.exec.enabled` esté en `true`.
2.  **Prueba el comando exec**: Pide a tu agente que enumere los archivos del directorio actual usando el comando `ls`.
3.  **Verifica el estado**: Usa `process` para ver si hay tareas en segundo plano si el comando tarda más de lo esperado.
4.  **Configura la búsqueda**: Añade tu `BRAVE_API_KEY` para que el agente pueda consultar información en tiempo real.

## Tool inventory

### `apply_patch`

Aplica parches estructurados en uno o más archivos. Úsalo para ediciones de varios fragmentos (multi-hunk).
Es una función experimental: actívala mediante `tools.exec.applyPatch.enabled` (solo para modelos de OpenAI).

### `exec`

Ejecuta comandos de shell en el workspace.

Parámetros principales:

- `command` (requerido)
- `yieldMs` (pasa a segundo plano automáticamente tras el tiempo de espera, por defecto 10000)
- `background` (pasa a segundo plano inmediatamente)
- `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 un sandbox)
- `host` (`sandbox | gateway | node`)
- `security` (`deny | allowlist | full`)
- `ask` (`off | on-miss | always`)
- `node` (ID/nombre del nodo para `host=node`)
- Si necesitas un TTY real, establece `pty: true`.

Notas:

- Devuelve `status: "running"` con un `sessionId` cuando se ejecuta en segundo plano.
- Usa `process` para consultar, registrar, escribir, matar o limpiar sesiones en segundo plano.
- Si `process` está deshabilitado, `exec` se ejecuta de forma síncrona e ignora `yieldMs`/`background`.
- `elevated` depende de `tools.elevated` y de cualquier anulación en `agents.list[].tools.elevated` (ambos deben permitirlo). Es un alias para `host=gateway` + `security=full`.
- `elevated` solo cambia el comportamiento cuando el agente está en un sandbox (de lo contrario, no hace nada).
- `host=node` puede dirigirse a una aplicación complementaria de macOS o a un host de nodo headless (`openclaw node run`).
- Para aprobaciones y listas permitidas de gateway/node, consulta [Exec approvals](/docs/tools/exec-approvals).

### `process`

Gestiona las sesiones de ejecución (`exec`) en segundo plano.

Acciones principales:

- `list`, `poll`, `log`, `write`, `kill`, `clear`, `remove`

Notas:

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

### `web_search`

Busca en la web utilizando la Brave Search API.

Parámetros principales:

- `query` (requerido)
- `count` (1–10; valor por defecto de `tools.web.search.maxResults`)

Notas:

- Requiere una Brave API key (recomendado: `openclaw configure --section web`, o establece `BRAVE_API_KEY`).
- Actívalo mediante `tools.web.search.enabled`.
- Las respuestas se guardan en caché (por defecto 15 min).
- Revisa [Web tools](/docs/tools/web) para la configuración.

### `web_fetch`

Obtiene y extrae contenido legible de una URL (convierte HTML a markdown o texto).

Parámetros principales:

- `url` (requerido)
- `extractMode` (`markdown` | `text`)
- `maxChars` (trunca páginas largas)

Notas:

- Actívalo mediante `tools.web.fetch.enabled`.
- `maxChars` está limitado por `tools.web.fetch.maxCharsCap` (por defecto 50000).
- Las respuestas se guardan en caché (por defecto 15 min).
- Para sitios con mucho JS, es mejor usar la herramienta `browser`.
- Revisa [Web tools](/docs/tools/web) y [Firecrawl](/docs/tools/firecrawl) para opciones anti-bot.

### `browser`

Controla el navegador dedicado gestionado por OpenClaw.

Acciones principales:

- `status`, `start`, `stop`, `tabs`, `open`, `focus`, `close`
- `snapshot` (aria/ai)
- `screenshot` (devuelve un 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`: enumera todos los perfiles con su estado.
- `create-profile`: crea un perfil con puerto auto-asignado (o `cdpUrl`).
- `delete-profile`: detiene el navegador y borra datos (solo local).
- `reset-profile`: mata procesos huérfanos en el puerto del perfil (solo local).

Notas:

- Requiere `browser.enabled=true`.
- Los nombres de perfil deben ser alfanuméricos en minúsculas y guiones (máx. 64 caracteres).
- Rango de puertos: 18800-18899 (máx. ~100 perfiles).
- `snapshot` usa `ai` por defecto si Playwright está instalado; usa `aria` para el árbol de accesibilidad.
- `act` requiere un `ref` de `snapshot`. Evita usar `wait` a menos que sea estrictamente necesario.

### `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:

- Utiliza `node.invoke` del gateway internamente.
- A2UI es solo para v0.8. El CLI rechazará JSONL de v0.9 con errores de línea.

### `nodes`

Descubre y apunta a nodos vinculados; envía notificaciones; captura cámara o pantalla.

Acciones principales:

- `status`, `describe`, `pending`, `approve`, `reject`
- `notify` (macOS `system.notify`)
- `run` (macOS `system.run`)
- `camera_snap`, `camera_clip`, `screen_record`, `location_get`

Ejemplo de `run`:

```json
{
  "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 requerida)
• prompt (opcional; por defecto “Describe the image.”)
• model (anulación opcional)

Notas:

• Solo disponible si agents.defaults.imageModel está configurado.
• Funciona de forma independiente al modelo de chat principal.

message

Envía mensajes y acciones en canales de Discord, Google Chat, Slack, Telegram, WhatsApp, Signal, iMessage y MS Teams.

Acciones principales:

• send (texto + media opcional; MS Teams admite card)
• poll (encuestas en WhatsApp/Discord/MS Teams)
• react, read, edit, delete, pin, thread-create, search, member-info, channel-list, entre otras.

Notas:

• send encamina WhatsApp vía Gateway; otros canales van directo.
• Las llamadas están restringidas al objetivo de la sesión activa para evitar fugas de contexto.

cron

Gestiona tareas cron del Gateway y activaciones.

Acciones principales:

• status, list, add, update, remove, run, runs, wake

gateway

Reinicia o aplica actualizaciones al proceso del Gateway en ejecución.

Acciones principales:

• restart (deshabilitado por defecto; activar con commands.restart: true)
• config.get, config.schema, config.apply, config.patch, update.run

sessions (Gestión de sesiones)

Herramientas como sessions_list, sessions_history, sessions_send, sessions_spawn y session_status.

Notas:

• sessions_spawn inicia la ejecución de un sub-agente y es no bloqueante (devuelve status: "accepted" de inmediato).
• sessions_send espera la completitud final si timeoutSeconds > 0.
• El intercambio entre agentes tiene un límite de turnos definido en session.agentToAgent.maxPingPongTurns.

agents_list

Enumera los IDs de agentes que la sesión actual puede usar con sessions_spawn. Los resultados están restringidos por las allowlists de cada agente.

Solución de problemas

• El comando exec no se ejecuta en segundo plano: Verifica si process está marcado como deshabilitado en tu configuración. Si es así, exec siempre será síncrono.
• Error al capturar pantalla o cámara: Asegúrate de que la aplicación del nodo esté en primer plano en el dispositivo de destino.
• No se encuentran perfiles de navegador: Recuerda que los perfiles remotos son solo de “adjuntar” (attach-only); no puedes iniciarlos o detenerlos directamente.
• Fallo en sessions_spawn: Revisa agents_list para confirmar que el agente tiene permiso para invocar al sub-agente deseado.

Para resolver dudas específicas sobre tu configuración, consulta al AI Setup Assistant.

Próximos pasos

• Configuración de Exec y aprobaciones
• Guía de herramientas Web
• Uso de Browser avanzado
• Gestión de nodos y periféricos

```mdx
---
title: "Configuración de parámetros comunes y flujos de trabajo"
description: "Aprende a configurar los parámetros esenciales de Gateway y Browser, y descubre los flujos recomendados para tus agentes."
---

Seguramente te ha pasado: intentas conectar tus herramientas al Gateway y algo falla porque las credenciales no se heredaron como esperabas, o tu agente se queda bloqueado sin saber qué herramienta llamar después. Configurar la comunicación entre componentes no debería ser un juego de adivinanzas.

Para que tus agentes funcionen bien, necesitas tener claros los parámetros de conexión y, sobre todo, cómo estructurar las llamadas para que el modelo entienda qué está pasando en cada paso.

## Requisitos previos

Para seguir esta guía, necesitas trabajar con los siguientes componentes mencionados en la documentación oficial:

*   Gateway-backed tools (`canvas`, `nodes`, `cron`)
*   Browser tool

## Inicio rápido

Configura tus herramientas en menos de 5 minutos siguiendo estas definiciones de parámetros.

### Parámetros para Gateway-backed tools

Si usas `canvas`, `nodes` o `cron`, estos son los parámetros que debes manejar:

*   `gatewayUrl`: Por defecto es `ws://127.0.0.1:18789`.
*   `gatewayToken`: Obligatorio si la autenticación está habilitada.
*   `timeoutMs`: Para controlar los tiempos de espera.

**Nota importante:** Cuando definas un `gatewayUrl`, incluye siempre el `gatewayToken` de forma explícita. Las herramientas no heredan configuraciones ni credenciales del entorno para sobrescrituras; si faltan las credenciales explícitas, tendrás un error.

### Parámetros para Browser tool

Para la herramienta de navegación, utiliza estas opciones:

*   `profile`: (Opcional) Por defecto usa `browser.defaultProfile`.
*   `target`: Puede ser `sandbox`, `host` o `node`.
*   `node`: (Opcional) Para fijar un ID o nombre de nodo específico.

## Flujos recomendados para el agente

No dejes que el agente improvise. Te recomiendo seguir estos flujos estructurados:

### Automatización de Browser
1.  `browser` → `status` / `start`
2.  `snapshot` (ai o aria)
3.  `act` (click/type/press)
4.  `screenshot` si necesitas confirmación visual

### Renderizado de Canvas
1.  `canvas` → `present`
2.  `a2ui_push` (opcional)
3.  `snapshot`

### Selección de Nodos (Node targeting)
1.  `nodes` → `status`
2.  `describe` sobre el nodo elegido
3.  `notify` / `run` / `camera_snap` / `screen_record`

## Seguridad

La seguridad no es negociable. Sigue estas reglas:

*   Evita usar `system.run` directamente. Prefiere `nodes` → `run` y solo con el consentimiento explícito del usuario.
*   Respeta siempre el consentimiento del usuario para capturas de cámara o pantalla.
*   Usa `status` o `describe` para verificar los permisos antes de lanzar comandos de contenido multimedia.

## Cómo se presentan las herramientas al agente

El agente recibe la información por dos canales paralelos. Es fundamental que ambos estén sincronizados:

1.  **System prompt text**: Una lista legible por humanos con guías de uso.
2.  **Tool schema**: Definiciones de funciones estructuradas enviadas a la API del modelo.

El modelo solo puede llamar a una herramienta si aparece en ambos sitios. Si no está en el prompt o en el schema, para el agente no existe.

## Solución de problemas

**Error: Credenciales ausentes al usar un `gatewayUrl` personalizado.**
*   **Solución**: Asegúrate de pasar el `gatewayToken` explícitamente en la configuración de la herramienta. Recuerda que las herramientas no heredan automáticamente las credenciales de las variables de entorno cuando sobrescribes la URL.

**El agente no puede ejecutar comandos de media (cámara/pantalla).**
*   **Solución**: Verifica los permisos primero usando los comandos `status` o `describe`. El flujo debe validar el acceso antes de intentar la captura.

¿Necesitas ayuda configurando tu entorno? Prueba nuestro [AI Setup Assistant](/docs/).

## Próximos pasos

*   [Configuración avanzada de Gateway](/docs/gateway/)
*   [Guía de uso de Browser tool](/docs/)
*   [Gestión de permisos en Nodes](/docs/)
*   [Referencia de API para Canvas](/docs/)