Herramientas: Descripción general

Las herramientas son las manos del agente. Una herramienta es una capacidad que el modelo puede invocar durante la conversación, ejecutar un comando de shell, obtener una URL HTTP, abrir un navegador, escribir un archivo, leer un sensor. Cada llamada a una herramienta está sujeta a la política de seguridad. Las ejecuciones satisfactorias pueden incluir un recibo de herramienta cuando los recibos están habilitados.

Las herramientas no deben confundirse con los subcomandos de la CLI de zeroclaw. Los comandos de la CLI son para los operadores; las herramientas son para el agente.

Un agente obtiene sus herramientas a través de los paquetes de habilidades, conocimiento y MCP que referencia; consulta Agents para ver cómo se adjuntan los paquetes a un agente. Para el recorrido a nivel de turno desde la llamada a la herramienta del proveedor hasta la aprobación, la distribución, la recepción, el evento del observador y la entrada del historial, consulta Tool execution lifecycle.

Antes de añadir una herramienta integrada o reemplazar una por una integración externa, use el Inventario de herramientas integradas para elegir el lugar estable más pequeño. Las integraciones integradas que funcionan siguen disponibles hasta que un reemplazo esté listo, documentado y revisado de forma independiente. Esa regla de reemplazo primero es la política aceptada en RFC #6165, y está registrada en la sección Política de reemplazo primero del inventario.

Herramientas mínimas y completas

Las configuraciones usan completo salvo que seleccionen mínimo: todas las herramientas integradas que incluye este binario y que permite su configuración existente, sus prerrequisitos y sus reglas de permisos. La configuración inicial y la generación de configuración escriben optional = ["*"]. Un archivo sin [tools], o una sección [tools] sin optional, también se carga como completo, por lo que al actualizar a v0.8.6 se mantiene la disponibilidad de herramientas existente. Las selecciones explícitas existentes se conservan.

[tools]
optional = ["*"] # completo; el predeterminado

Mínimo es opcional: once herramientas integradas en Chat, u ocho en Code/ACP, que mantiene su exclusión de las herramientas de memoria persistente. Las once de Chat son shell, file_read, file_write, file_edit, glob_search, content_search, memory_recall, memory_store, memory_forget, web_fetch y git_operations. La política existente puede restringir cualquiera de los dos catálogos.

[tools]
optional = [] # minimal

Para el mínimo más los extras seleccionados, utiliza sus nombres invocables:

[tools]
optional = ["calculator", "cron_list", "sessions_history"]

El comodín es una unión con entradas nombradas: ["*", "calculator"] tiene la misma selección que ["*"], sin herramienta duplicada. Full no es un recuento fijo de herramientas; las integraciones configuradas, las capacidades de ejecución y la política determinan el catálogo efectivo. No habilita todas las integraciones. Seleccionar una herramienta no instala un navegador ni una CLI de proveedor, no proporciona credenciales, no habilita una integración deshabilitada ni concede permisos. Full también conserva la exclusión de memoria existente en Code/ACP.

Stop: this is a translation request for documentation text, so I’ll return only the Spanish version.

La selección ocurre antes de que se ejecuten los constructores. Una herramienta no seleccionada no aporta texto de esquema ni de catálogo de herramientas al prompt. Los perfiles de riesgo, la restricción por parte del llamador, la aprobación, las políticas de ruta y de red, y los recibos siguen aplicándose. Los servidores MCP, las skills, los plugins y los periféricos explícitos conservan sus rutas de activación y autoridad existentes. La divulgación progresiva de esquemas es una función independiente y no forma parte de estos ajustes.

Para elegir la opción mínima, establece optional = [] en [tools], o ejecuta:

zeroclaw config set tools.optional [] --no-interactive

Recarga el daemon después de cambiar la selección. El esquema de configuración sigue en la versión 3. zeroclaw config migrate registra optional = ["*"] en un archivo existente que no tiene [tools]; los guardados ordinarios también conservan la intención del selector.

Compilaciones y ruta de actualización

Una matriz de publicación tiene diez variantes de destino, con nombres de archivo sin cambios. Android es experimental y se permite que falle; la publicación requiere los otros nueve destinos. No existe una segunda matriz de archivos de compatibilidad ni una imagen dedicada compat-tools. La imagen Docker histórica all-features sigue siendo más amplia que dist, e incluye canales adicionales y funciones de hardware.

dist incluye tools-compat (tools-saas, tools-coding-cli, tools-external). dist-compat es un alias de compatibilidad para el mismo build. Los valores predeterminados de Cargo sin más siguen siendo más reducidos: los builds de código fuente personalizados pueden omitir adaptadores. Un adaptador externo excluido en la compilación y nombrado en optional recibe un diagnóstico claro; full selecciona solo los adaptadores que este binario incluye y no informa nada sobre el resto. Las secciones de proveedor o CLI habilitadas conservan su diagnóstico existente de característica faltante. La configuración en tiempo de ejecución no puede añadir código excluido en la compilación. Compila la selección estándar para recuperarlo:

# Desde un checkout del código fuente; usa el destino que pretendas ejecutar.
TARGET=The input is a single identifier (target triple), so it is returned unchanged.

x86_64-unknown-linux-gnu
FEATURES="$(cargo run --quiet --locked -p xtask --bin generate -- features --selection dist --target "$TARGET")"
cargo build --release --locked --bin zeroclaw --target $TARGET --no-default-features --features $FEATURES
# Para una imagen Linux local, resuelve las funciones para su destino de compilación.
docker build -t zeroclaw-dist-local .

Para una instalación de Homebrew cuya fórmula omite los adaptadores, ejecute el binario estándar compilado desde el código fuente junto con el binario gestionado por el gestor de paquetes, y use sus propias rutas de configuración, datos y servicio. Un ajuste de configuración no puede cambiar las funciones compiladas de un bottle. Los usuarios que compilan desde el código fuente también pueden seleccionar funciones tool-* individuales existentes o tools-compat; aun así, necesitan la selección en tiempo de ejecución.

El dist estándar incluye el host de plugins y plugins-wasm-cranelift en los siete objetivos nativos de 64 bits compatibles: Linux GNU y musl en x86_64 y aarch64, ambas arquitecturas de macOS, y Windows x86_64 con MSVC. ARMv6/ARMv7 omiten Cranelift y Prometheus; Android experimental omite Cranelift y WhatsApp Web. Los valores predeterminados de Cargo no incluyen un host de plugins. Compilar el host deja plugins.enabled y plugins.auto_discover en false; el consentimiento, la confianza, las concesiones y la activación configurada siguen aplicándose. El soporte solo en tiempo de ejecución para .cwasm precompilados y Pulley no sustituye la compilación portable de .wasm del registro. La política de objetivos proviene de package.metadata.zeroclaw en Cargo.toml.

Minimal es una selección de catálogo en tiempo de ejecución. La distribución estándar dist sigue incluyendo los adaptadores nativos compilados, por lo que minimal por sí solo no es evidencia del tamaño del binario para el trabajo de extracción de herramientas. Los valores predeterminados de Container, Kubernetes y Nix omiten [tools] y se cargan completos como cualquier otra configuración; establezca optional = [] en ellos para minimal.

Herramientas integradas

Las siguientes capacidades integradas están disponibles cuando se compilan y se seleccionan; full las incluye todas. El conjunto mínimo de once herramientas aparece arriba. Esta lista no es el conjunto básico; consulta Niveles y el conjunto básico conservado para ver el conjunto básico y el nivel de cada herramienta que construye el registro de tiempo de ejecución.

AnySearch provider

AnySearch es un backend explícito y opcional para web_search_tool:

[web_search]
search_provider = "anysearch"
# Opcional; omítala para usar la cuota anónima de AnySearch, más baja y con límite de velocidad.
anysearch_api_key = "..."

Las consultas de búsqueda y el límite de resultados configurado se envían a https://api.anysearch.com/v1/search. Cuando anysearch_api_key está configurado, ZeroClaw lo envía únicamente como encabezado de autorización Bearer; sin clave, no se envía ningún encabezado Authorization. Por tanto, seleccionar este proveedor envía las consultas de búsqueda a un servicio de terceros incluso en modo anónimo. No cambia el proveedor predeterminado ni se usa como alternativa automática.

Herramientas integradas adicionales de origen propio, incluidas en la versión completa pero no en la mínima:

Las herramientas seleccionadas también mantienen estos requisitos previos:

Descubrimiento de esquema integrado

Habilita deferred_builtin_tools en el perfil de runtime del agente mediante el editor de ZeroCode Config para reducir el catálogo de herramientas integradas que se envía al modelo. Su valor predeterminado es false, lo que mantiene la carga anticipada de esquemas. La opción es independiente de la opción deferred_loading de MCP.

Cuando está habilitado, los esquemas permitidos de shell, file_read, file_write, file_edit, memory_recall y memory_store siguen visibles. Las demás herramientas integradas habilitadas aparecen en una lista compacta de descubrimiento. El modelo usa tool_search con palabras clave o select:<tool_name> para recuperar las definiciones completas. Los esquemas seleccionados aparecen en las solicitudes posteriores de herramientas nativas; los proveedores de texto reciben la definición en el resultado de la búsqueda.

El descubrimiento nunca concede permisos ni cambia la aprobación de herramientas. Las políticas del agente, las restricciones del principal y las listas de permitidos del llamador siguen aplicándose, incluso después de que una sesión restrinja sus herramientas. Los ejecutables integrados permanecen en el registro con alcance existente, por lo que el enrutamiento de memoria no conserva una instancia de herramienta separada y obsoleta. Si la política no admite tool_search, los esquemas integrados restantes siguen cargados en modo eager. Los endpoints de listado de herramientas siguen mostrando el registro admitido completo.

Protocolos de extensión

Además de las herramientas integradas, ZeroClaw admite la superficie de extensión MCP (Protocolo de Contexto del Modelo). Conecta cualquier servidor MCP (el sistema de archivos de Claude Code, Playwright, el tuyo propio) y el agente detectará sus herramientas al inicio.

Para la integración del lado del IDE donde un editor ejecuta ZeroClaw como subproceso, consulta ACP: Agent Client Protocol se encuentra bajo channels porque es una superficie de gestión de sesiones entrante, no una herramienta que el agente invoca.

Creación de una herramienta

Implementa el rasgo Tool en zeroclaw-api:

#![allow(unused)]
fn main() {
#[async_trait]
pub trait Tool: Send + Sync + Attributable {
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn parameters_schema(&self) -> serde_json::Value;   // Esquema JSON para args
    async fn execute(&self, args: serde_json::Value) -> anyhow::Result<ToolResult>;
}
}

Cada Tool es también Attributable, por lo que las emisiones de log y los rastros de auditoría de una llamada a herramienta llevan la misma atribución <kind>.<alias> que usa el resto del runtime.

Regístrate a través de la fábrica de herramientas del entorno de ejecución. Consulta Desarrollo → Protocolo de plugins para ver el patrón completo.

Descripción de herramientas para el modelo

Las descripciones de herramientas son cadenas Mozilla Fluent: una por herramienta, localizada por configuración regional. Esto mantiene las descripciones de herramientas concisas en la ventana de contexto del modelo, a la vez que permite la localización de la interfaz de usuario.

Fuente de verdad: crates/zeroclaw-runtime/locales/en/tools.ftl. Las traducciones se generan y mantienen mediante cargo fluent fill --locale <code> (consulta Mantenedores → Documentación y traducciones).

Riesgo y aprobación

Cada invocación de herramienta se clasifica por riesgo:

• Bajo (solo lectura, sin efectos secundarios): file_read, memory_recall, http_request GET a dominios permitidos
• Medio (muta el estado local): file_write, shell con comandos conocidos seguros
• Alto (efectos secundarios destructivos o remotos): shell con comandos desconocidos, http_request POST a URLs sin restricciones

El nivel de autonomía determina lo que puede hacer cada nivel de riesgo sin la aprobación del operador. Predeterminado (Supervised): las ejecuciones de bajo nivel, las de nivel medio solicitan, y las de alto nivel bloquean.

Cuando los recibos están habilitados, las ejecuciones exitosas reciben un recibo de herramienta. Las llamadas denegadas, bloqueadas, reemplazadas, fallidas o interrumpidas no reciben recibos.

Desactivar herramientas en canales que no son CLI

El esquema no tiene un campo tools_allow / tools_deny por canal. El control de acceso a herramientas reside en el perfil de riesgo del agente ([risk_profiles.<alias>]):

• excluded_tools elimina las herramientas listadas de todos los canales que no sean CLI (Discord, Telegram, Bluesky, Matrix, Slack, etc.) y deja intacta la CLI local. La granularidad es binaria (CLI frente a no CLI), no por canal. Además, resta de la lista de अनुमति permitida de agentic-delegate resuelta en tiempo de ejecución, que es la única forma de bloquear nombres MCP individuales <server>__<tool> que de otro modo serían admitidos automáticamente por la regla siguiente.
• allowed_tools es una lista de permitidos. Omitirla y una lista vacía explícita (allowed_tools = []) significan el mismo estado heredado: sin restricción de autorización. Una lista no vacía es un conjunto cerrado para las herramientas integradas (y, mediante la excepción de MCP que se describe más abajo, admite automáticamente las herramientas MCP con espacio de nombres). Una lista vacía no significa denegar todo; para eso, establezca la clave hermana deny_all_tools = true, que deniega por igual las herramientas integradas, las herramientas MCP y las herramientas definidas por skills. Establecer a la vez deny_all_tools = true y una allowed_tools no vacía es un error de configuración que se rechaza al cargar.
• Excepción de MCP: cuando allowed_tools no está vacío, las herramientas MCP descubiertas en tiempo de ejecución (cualquier nombre que contenga __, la convención <server>__<tool>) se admiten automáticamente en la lista de अनुमति efectiva sin necesidad de enumerarlas allí individualmente. Esto mantiene utilizable el valor predeterminado eager-MCP posterior a #7464 para agentes que ya fijan una lista de अनुमति explícita. Para bloquear herramientas MCP individuales, enuméralas en excluded_tools.
• La excepción de MCP está limitada solo a allowed_tools del perfil de riesgo. Las listas de अनुमति por ejecución suministradas por el llamador (allowed_tools del trabajo de cron, invocaciones delegadas reducidas, etc.) siguen tratándose como intersecciones estrictas de listas explícitas. Un trabajo que se restringe a allowed_tools = ["cron_add"] no expondrá los envoltorios de MCP descubiertos en tiempo de ejecución que no haya nombrado, incluso cuando el perfil de riesgo del agente los admitiría automáticamente.

Si necesitas un control más fino bajo la autonomía Full, coloca las herramientas sensibles en la lista always_ask del perfil: seguirán solicitando confirmación (o fallarán de forma segura) incluso cuando level = "full". Cambiar el perfil a read_only o supervised solo es necesario cuando quieres toda la matriz de niveles de riesgo, no cuando necesitas unas pocas excepciones.

Consulta Niveles de autonomía para ver el conjunto completo de campos por perfil.

Ver también

• MCP
• Ciclo de vida de ejecución de herramientas
• ACP
• Automatización del navegador
• Seguridad → Resumen