← Volver al listado de tecnologías ← Índice de OpenCode

Capitulo 7: Herramientas Built-in

4 de abril de 2026 Por: Artiko

opencodeaiherramientastoolspermisos

Capitulo 7: Herramientas Built-in

Las herramientas son las capacidades concretas que OpenCode le da al LLM para interactuar con tu sistema. Cada herramienta tiene un propósito específico, un conjunto de parámetros y un nivel de permiso configurable. Entender qué hace cada una y cómo configurar sus permisos es esencial para un flujo de trabajo seguro y productivo.

OpenCode incluye 15 herramientas built-in organizadas en 6 categorías: archivos, búsqueda, ejecución, web, code intelligence y workflow. Juntas, cubren prácticamente todas las operaciones que un desarrollador necesita durante una sesión de codificación asistida por IA.

Visión General

graph TD
    A[Herramientas Built-in] --> B[Archivos]
    A --> C[Busqueda]
    A --> D[Ejecucion]
    A --> E[Web]
    A --> F[Code Intelligence]
    A --> G[Workflow]
    B --> B1[read]
    B --> B2[write]
    B --> B3[edit]
    B --> B4[apply_patch]
    C --> C1[grep]
    C --> C2[glob]
    C --> C3[list]
    D --> D1[bash]
    E --> E1[webfetch]
    E --> E2[websearch]
    F --> F1[lsp]
    G --> G1[skill]
    G --> G2[todowrite]
    G --> G3[question]

Herramientas de Archivos

Las herramientas de archivos son el núcleo de la interacción con el código. Permiten leer, crear, modificar y parchear archivos del proyecto.

read

Lee el contenido de archivos. Soporta rangos de línea para leer secciones específicas sin cargar todo el archivo en la ventana de contexto del LLM.

Uso típico:

read archivo.ts          # Lee el archivo completo
read archivo.ts 10-50    # Lee las líneas 10 a 50

La capacidad de leer rangos es crítica para archivos grandes. En vez de consumir tokens leyendo un archivo de 2000 líneas completo, puedes pedir solo la sección relevante. Esto optimiza el uso del contexto y permite al LLM mantener más información útil en memoria.

Cuándo se usa: Cada vez que el LLM necesita entender código existente antes de modificarlo, buscar una función específica, revisar la estructura de un archivo o verificar el resultado de una edición anterior. Es la herramienta más invocada en cualquier sesión típica.

write

Crea archivos nuevos o sobrescribe completamente archivos existentes con contenido nuevo. Reemplaza todo el contenido del archivo de una vez.

Uso típico:

write nuevo-archivo.ts [contenido completo]

Write es la herramienta para crear archivos desde cero. Cuando el LLM necesita generar un archivo nuevo (un componente, un test, una configuración), usa write. También se usa cuando el archivo existente necesita ser reemplazado completamente.

Importante: Write está controlado por los permisos de edit. Si edit está en deny, write también estará bloqueado. Esto tiene sentido porque sobrescribir un archivo es una forma de edición destructiva.

Cuándo usarlo vs. edit: Usa write para archivos nuevos o reescrituras completas. Usa edit para modificaciones parciales. La regla general es que si más del 80% del archivo cambia, write es más eficiente. Si solo cambias unas pocas líneas, edit es más seguro y preciso.

edit

Realiza reemplazos exactos de texto dentro de un archivo. Busca un string exacto en el archivo y lo reemplaza por otro string. Solo modifica la parte especificada, dejando el resto intacto.

Uso típico:

edit archivo.ts [old_string] [new_string]

Edit es la herramienta preferida para modificaciones parciales porque minimiza el riesgo de alterar contenido no relacionado. Al requerir una coincidencia exacta del texto a reemplazar, el LLM debe ser preciso sobre qué está cambiando. Esto reduce errores comparado con reescribir el archivo completo.

Ventajas sobre write:

Solo modifica lo necesario, preservando el resto del archivo intacto
Más seguro: si el old_string no coincide exactamente, la operación falla sin modificar nada
Más eficiente en tokens: solo envía los fragmentos que cambian
Permite al LLM hacer múltiples ediciones incrementales en un archivo

Cuándo se usa: Para corregir bugs específicos, añadir imports, modificar funciones, actualizar configuraciones parciales y cualquier cambio que afecte solo una parte del archivo.

apply_patch

Aplica archivos de parches en formato diff a un archivo. Permite múltiples cambios complejos en diferentes partes de un archivo en una sola operación.

Uso típico:

apply_patch archivo.ts [contenido del patch]

Apply_patch es ideal cuando hay múltiples cambios distribuidos en diferentes partes del archivo que sería tedioso hacer uno por uno con edit. Un solo patch puede añadir imports arriba, modificar una función en el medio y actualizar exports abajo.

Nota: Apply_patch está controlado por los permisos de edit. Si edit está bloqueado, apply_patch también lo estará.

Cuándo usarlo vs. edit: Usa apply_patch cuando necesitas hacer muchos cambios distribuidos en un archivo. Usa edit cuando el cambio es puntual y localizado. Apply_patch es especialmente útil en refactorizaciones donde múltiples partes del archivo cambian coordinadamente.

Herramientas de Búsqueda

Las herramientas de búsqueda permiten al LLM encontrar información en el codebase sin necesidad de leer archivos completos. Son fundamentales para la fase de exploración y análisis.

grep

Busca patrones en archivos usando expresiones regulares. Funciona como ripgrep con capacidad de buscar en todo el proyecto, filtrar por extensión y mostrar contexto alrededor de las coincidencias.

Uso típico:

grep "function.*export" --include="*.ts"
grep "TODO|FIXME" --include="*.{ts,js}"

Grep es la herramienta de búsqueda más potente. Con expresiones regulares puedes buscar patrones complejos: funciones que exportan cierto tipo, variables que siguen un patrón de nombre, imports de un módulo específico, etc.

Capacidades avanzadas:

Filtros por extensión de archivo
Exclusión de directorios (node_modules, dist, etc.)
Contexto configurable alrededor de las coincidencias
Búsqueda sensible o insensible a mayúsculas

Cuándo se usa: Para encontrar dónde se usa una función, buscar patrones de código, localizar configuraciones, encontrar TODOs pendientes y cualquier búsqueda basada en contenido de archivos.

glob

Encuentra archivos que coincidan con patrones de nombre. No busca dentro del contenido, solo localiza archivos por su nombre y ruta.

Uso típico:

glob "src/**/*.test.ts"
glob "**/config.*"
glob "**/*.{ts,tsx}" --exclude="node_modules"

Glob es complementario a grep. Mientras grep busca contenido, glob busca archivos por nombre. Es más rápido que grep cuando solo necesitas saber si un archivo existe o listar archivos que siguen una convención de nombres.

Cuándo se usa: Para encontrar archivos de test, configuraciones, archivos de un tipo específico, verificar convenciones de nombres y explorar la estructura de carpetas del proyecto.

list

Lista directorios mostrando archivos y carpetas con opción de filtro glob. Proporciona una vista de la estructura del proyecto.

Uso típico:

list src/
list src/ --filter="*.ts"

List es la forma más directa de explorar la estructura de un proyecto. El LLM la usa frecuentemente al inicio de una sesión para entender cómo está organizado el código.

Cuándo se usa: Para explorar la estructura del proyecto, entender la organización de carpetas, verificar si un directorio existe y obtener una visión general de los archivos en un módulo.

Ejecución

bash

Ejecuta comandos shell en el sistema operativo. Es la herramienta más poderosa y la que más precaución requiere.

Uso típico:

bash npm test
bash git status
bash docker ps
bash bun run build

Bash puede ejecutar cualquier comando disponible en tu sistema: compiladores, test runners, herramientas de git, gestores de paquetes, Docker, scripts personalizados y cualquier binario instalado. Los comandos se ejecutan en el directorio del proyecto por defecto.

Por qué requiere precaución: A diferencia de las herramientas de archivos que operan archivo por archivo, bash puede ejecutar comandos con efectos amplios e irreversibles. Un rm -rf mal dirigido o un git push --force pueden causar daños serios. Por eso el permiso por defecto es ask.

Cuándo se usa: Para compilar el proyecto, ejecutar tests, interactuar con git, instalar dependencias, ejecutar scripts de build, verificar el estado de servicios y cualquier operación que requiera la línea de comandos.

Web

webfetch

Obtiene el contenido de páginas web y lo convierte a texto legible para el LLM. Útil para consultar documentación, APIs o referencias externas durante una sesión.

Uso típico:

webfetch https://docs.ejemplo.com/api
webfetch https://github.com/proyecto/README.md

El contenido se procesa eliminando HTML, scripts y estilos para presentar solo el texto relevante. Esto permite al LLM consultar documentación actualizada sin salir de la sesión.

Cuándo se usa: Para consultar documentación oficial de librerías, verificar la API de un servicio, leer changelogs de actualizaciones y obtener información que el LLM no tiene en su entrenamiento.

websearch

Realiza búsquedas web usando Exa AI. No requiere API key del usuario para funcionar, lo que simplifica la configuración.

Uso típico:

websearch "cómo configurar nginx reverse proxy con websockets"
websearch "error CORS fetch API solución"

Devuelve resultados relevantes que el LLM puede usar para responder preguntas o resolver problemas que van más allá del codebase local.

Cuándo se usa: Para buscar soluciones a errores, encontrar documentación de tecnologías, investigar mejores prácticas y obtener información actualizada sobre temas que el LLM necesita para completar una tarea.

Code Intelligence

lsp (Experimental)

Interactúa con Language Servers del proyecto. Permite obtener información semántica del código que va más allá de la búsqueda de texto: definiciones reales de tipos, referencias cruzadas, información de hover y diagnósticos.

Uso típico:

lsp goto-definition archivo.ts 15 20
lsp references archivo.ts 15 20
lsp hover archivo.ts 15 20

LSP proporciona al LLM comprensión semántica del código. Mientras grep busca texto, LSP entiende la estructura: sabe que una función se llama desde tres lugares, conoce el tipo exacto de una variable y puede encontrar la definición original de un símbolo importado.

Capacidades:

goto-definition: navegar a la definición de un símbolo
references: encontrar todos los usos de un símbolo
hover: obtener información de tipo y documentación
diagnostics: obtener errores y advertencias del compilador

Estado experimental: Al ser experimental, su disponibilidad y estabilidad pueden variar según el lenguaje, el language server instalado y la configuración del proyecto. Funciona mejor con lenguajes que tienen language servers maduros como TypeScript, Rust y Go.

Workflow

Las herramientas de workflow ayudan al LLM a gestionar tareas complejas y mantener organización durante sesiones largas.

skill

Carga archivos SKILL.md bajo demanda. Los skills son instrucciones predefinidas que el agente puede cargar cuando las necesita, funcionando como documentación especializada que expande las capacidades del agente para tareas específicas.

Uso típico:

skill deploy
skill testing

Los skills se definen como archivos Markdown con instrucciones detalladas para tareas recurrentes. Cuando el LLM carga un skill, incorpora esas instrucciones a su contexto actual.

Cuándo se usa: Para cargar instrucciones de deploy, protocolos de testing, guías de estilo de código y cualquier conocimiento especializado que no necesita estar presente en todas las sesiones.

todowrite

Crea o actualiza listas de tareas durante la sesión. El LLM las usa para planificar y rastrear progreso en tareas complejas que requieren múltiples pasos.

Uso típico:

todowrite [lista de items con estado]

Cada item puede estar marcado como pendiente, en progreso o completado. Las listas de tareas persisten durante la sesión y sobreviven a la compactación de contexto, lo que las hace especialmente valiosas en sesiones largas.

Cuándo se usa: Para descomponer tareas complejas en pasos manejables, rastrear progreso durante refactorizaciones grandes y mantener un plan de trabajo visible durante la sesión.

question

Pregunta al usuario cuando el LLM necesita información o clarificación que no puede inferir del contexto. Pausa la ejecución hasta recibir respuesta.

Uso típico:

question "Quieres que use PostgreSQL o SQLite para la base de datos?"

Question es fundamental para decisiones que el LLM no debe tomar solo. En vez de asumir, pregunta explícitamente y espera la respuesta del usuario antes de continuar.

Cuándo se usa: Para decisiones de arquitectura, preferencias de estilo, elección entre alternativas válidas y cualquier situación donde la respuesta correcta depende del criterio del usuario.

Sistema de Permisos

Cada herramienta tiene un nivel de permiso configurable que controla si se ejecuta libremente, requiere confirmación o está completamente bloqueada.

Permiso	Comportamiento
`allow`	Se ejecuta sin preguntar al usuario
`ask`	Pide aprobación antes de cada ejecución
`deny`	Completamente deshabilitada para el agente

Configurar Permisos en opencode.json

{
  "permissions": {
    "read": "allow",
    "write": "ask",
    "edit": "ask",
    "bash": "ask",
    "grep": "allow",
    "glob": "allow",
    "list": "allow",
    "webfetch": "ask",
    "websearch": "ask"
  }
}

Permisos Granulares para Bash

Bash es la herramienta que más se beneficia de permisos granulares. Puedes definir patrones glob para permitir automáticamente comandos seguros y bloquear los peligrosos:

{
  "permissions": {
    "bash": {
      "default": "ask",
      "allow": [
        "npm test*",
        "npm run lint*",
        "git status",
        "git diff*",
        "git log*",
        "ls*",
        "bun test*",
        "bun run build*"
      ],
      "deny": [
        "rm -rf*",
        "sudo*",
        "git push --force*",
        "git reset --hard*"
      ]
    }
  }
}

Con esta configuración:

Comandos de test, lint y git informativo se ejecutan sin preguntar
Comandos destructivos como rm -rf y git push --force están completamente bloqueados
Cualquier otro comando pide confirmación antes de ejecutar

Esto permite un flujo ágil donde los comandos seguros no interrumpen y los peligrosos tienen protección explícita.

Tabla de Referencia Completa

Herramienta	Categoría	Descripción	Permiso Default
`read`	Archivos	Leer archivos con rangos de línea	allow
`write`	Archivos	Crear/sobrescribir archivos	ask
`edit`	Archivos	Reemplazos exactos en archivos	ask
`apply_patch`	Archivos	Aplicar patches diff	ask
`grep`	Búsqueda	Buscar con regex en archivos	allow
`glob`	Búsqueda	Buscar archivos por patrón de nombre	allow
`list`	Búsqueda	Listar directorios con filtros	allow
`bash`	Ejecución	Ejecutar comandos shell	ask
`webfetch`	Web	Obtener páginas web como texto	ask
`websearch`	Web	Buscar en la web vía Exa AI	ask
`lsp`	Intelligence	Language Server Protocol	allow
`skill`	Workflow	Cargar archivos SKILL.md	allow
`todowrite`	Workflow	Gestionar listas de tareas	allow
`question`	Workflow	Preguntar al usuario	allow

Principio de Mínimo Privilegio

La recomendación general para configurar permisos sigue un patrón claro basado en el nivel de riesgo:

flowchart LR
    A[Solo lectura] -->|allow| B[read, grep, glob, list, lsp]
    C[Modificación] -->|ask| D[write, edit, apply_patch, bash]
    E[Red/externo] -->|ask| F[webfetch, websearch]
    G[Workflow] -->|allow| H[skill, todowrite, question]

allow para herramientas de solo lectura que no pueden causar daño (read, grep, glob, list)
ask para herramientas que modifican archivos o ejecutan comandos (write, edit, bash)
ask para herramientas que acceden a la red (webfetch, websearch)
allow para herramientas de workflow internas (skill, todowrite, question)
deny para herramientas que no necesitas en un contexto específico

Este balance entre productividad y seguridad es el punto de partida recomendado. A medida que ganas confianza con OpenCode, puedes relajar permisos de herramientas que usas frecuentemente y que consideras seguras en tu contexto.

Siguiente: Capitulo 8: Custom Tools —>