Capitulo 7: Herramientas Built-in

< Volver al Indice del Tutorial

Las herramientas son las capacidades que OpenCode le da al LLM para interactuar con tu sistema. Cada herramienta tiene un proposito especifico y un nivel de permiso configurable.

Herramientas de Archivos

read

Lee el contenido de archivos. Soporta rangos de linea para leer secciones especificas sin cargar todo el archivo en el contexto.

read archivo.ts          # Lee el archivo completo
read archivo.ts 10-50    # Lee las lineas 10 a 50

Util para archivos grandes donde solo necesitas una seccion.

write

Crea archivos nuevos o sobrescribe archivos existentes con contenido nuevo. Reemplaza todo el contenido del archivo.

write nuevo-archivo.ts [contenido]

Usa write cuando necesitas crear un archivo desde cero o reemplazar completamente su contenido.

edit

Realiza reemplazos exactos dentro de un archivo. Busca un string exacto y lo reemplaza por otro. Mas preciso que write porque solo modifica la parte necesaria.

edit archivo.ts [old_string] [new_string]

Es la herramienta preferida para modificaciones parciales porque minimiza el riesgo de alterar contenido no relacionado.

patch

Aplica patches en formato diff a un archivo. Util para cambios multiples y complejos en un solo archivo.

patch archivo.ts [diff content]

Ideal cuando hay multiples cambios distribuidos en diferentes partes del archivo.

Herramientas de Busqueda

grep

Busca patrones en archivos usando expresiones regulares. Equivalente a ripgrep con capacidad de buscar en todo el proyecto.

grep "funcion.*export" --include="*.ts"

Soporta filtros por extension, exclusion de directorios y contexto alrededor de las coincidencias.

glob

Encuentra archivos que coincidan con patrones de nombre. No busca contenido, solo nombres y rutas.

glob "src/**/*.test.ts"
glob "**/config.*"

Util para encontrar archivos por convencion de nombres o extension.

list

Lista directorios con opcion de filtro. Muestra la estructura de archivos y carpetas.

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

Perfecto para explorar la estructura del proyecto rapidamente.

Ejecucion

bash

Ejecuta comandos shell en el sistema. Es la herramienta mas poderosa y potencialmente peligrosa.

bash npm test
bash git status
bash docker ps

Por defecto requiere aprobacion del usuario antes de ejecutar. Los comandos se ejecutan en el directorio del proyecto.

Web

webfetch

Obtiene el contenido de paginas web y lo convierte a texto. Util para consultar documentacion, APIs o referencias externas.

webfetch https://docs.ejemplo.com/api

El contenido se procesa y se presenta al LLM en formato legible.

websearch

Realiza busquedas web usando Exa AI. Requiere configurar la variable de entorno OPENCODE_ENABLE_EXA.

websearch "como configurar nginx reverse proxy"

Devuelve resultados relevantes que el LLM puede usar para responder preguntas o resolver problemas.

Code Intelligence

lsp (Experimental)

Interactua con Language Servers del proyecto. Permite obtener informacion semantica del codigo: definiciones, referencias, diagnosticos y mas.

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

Al ser experimental, su disponibilidad y estabilidad pueden variar segun el lenguaje y la configuracion del proyecto.

Skills

skill

Carga archivos SKILL.md bajo demanda. Los skills son instrucciones predefinidas que el agente puede cargar cuando las necesita.

skill deploy
skill testing

Los skills se definen como archivos Markdown con instrucciones especificas para tareas recurrentes.

Workflow

todowrite

Crea o actualiza listas de tareas. El LLM las usa para planificar y rastrear progreso en tareas complejas.

todowrite [lista de items con estado]

Cada item puede estar marcado como pendiente, en progreso o completado.

todoread

Lee las listas de tareas existentes para verificar el progreso.

todoread

Permite al LLM consultar que tareas quedan pendientes y cual es el estado actual.

question

Pregunta al usuario cuando necesita informacion o clarificacion. Pausa la ejecucion hasta recibir respuesta.

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

Fundamental para decisiones que el LLM no debe tomar solo.

Sistema de Permisos

Cada herramienta tiene un nivel de permiso configurable:

Permiso	Comportamiento
allow	Se ejecuta sin preguntar al usuario
ask	Pide aprobacion antes de cada ejecucion
deny	Completamente deshabilitada

Configurar Permisos en opencode.json

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

Permisos con Glob Patterns para Bash

Puedes ser mas granular con los comandos bash usando patrones:

{
  "permissions": {
    "bash": {
      "default": "ask",
      "allow": [
        "npm test*",
        "npm run lint*",
        "git status",
        "git diff*",
        "ls*"
      ],
      "deny": [
        "rm -rf*",
        "sudo*"
      ]
    }
  }
}

Esto permite que comandos seguros se ejecuten automaticamente mientras los peligrosos se bloquean o requieren confirmacion.

Tabla de Referencia

Herramienta	Descripcion	Permiso Default
read	Leer archivos (con rangos)	allow
write	Crear/sobrescribir archivos	ask
edit	Reemplazos exactos en archivos	ask
patch	Aplicar patches diff	ask
grep	Buscar con regex	allow
glob	Buscar por patron de nombre	allow
list	Listar directorios	allow
bash	Ejecutar comandos shell	ask
webfetch	Obtener paginas web	ask
websearch	Buscar en la web (Exa)	ask
lsp	Language Server Protocol	allow
skill	Cargar SKILL.md	allow
todowrite	Crear/actualizar listas	allow
todoread	Leer listas de tareas	allow
question	Preguntar al usuario	allow

Principio de Minimo Privilegio

La recomendacion general es:

• allow para herramientas de solo lectura (read, grep, glob, list)
• ask para herramientas que modifican (write, edit, patch, bash)
• deny para herramientas que no necesitas en un contexto especifico

Esto balancea productividad con seguridad. Puedes ajustar segun tu nivel de confianza y el tipo de proyecto.

---

Siguiente: Capitulo 8: Custom Tools —>