OpenCode Herramientas personalizadas

Las herramientas personalizadas (Custom Tools) te permiten ampliar las capacidades de OpenCode, haciendo que el LLM llame a las funciones que defines durante la conversación, logrando así operaciones complejas como consultas a bases de datos, ejecución de scripts y llamadas a API.

Estas herramientas trabajan junto con las herramientas integradas (comoread、write、bash) para construir un sistema completo de capacidades de desarrollo automatizado.

Las herramientas personalizadas son la capacidad de extensión principal de OpenCode; elevan al LLM de solo generar código a poder ejecutar tareas.

Diseñando herramientas de forma adecuada, puedes construir:

  • Pipelines de desarrollo automatizado
  • Asistentes de código inteligentes
  • Sistemas de operación y mantenimiento con IA
  • Plataformas de herramientas de IA internas de la empresa

1. Qué son las herramientas personalizadas

Una herramienta personalizada es esencialmente una interfaz de función que el LLM puede llamar activamente durante la ejecución y obtener los resultados de la misma.

Escenarios de aplicación típicos:

  • Consultar bases de datos (SQL / NoSQL)
  • Invocar APIs internas
  • Ejecutar scripts (Python / Shell)
  • Leer el estado del sistema o información del entorno
  • Encapsular lógica de negocio compleja

Puedes entenderlo como:Un mecanismo de complementos que otorga a la IA capacidades de ejecución。

2. Ubicación de almacenamiento de las herramientas

OpenCode carga automáticamente las herramientas de los siguientes directorios:

  • Nivel de proyecto:.opencode/tools/
  • Nivel global:~/.config/opencode/tools/

El nombre del archivo es el nombre de la herramienta (muy importante).

3. Definición básica de herramientas (método recomendado)

Utilicetool()la función auxiliar para obtener seguridad de tipos y capacidad de validación de parámetros.

import { tool } from "@opencode-ai/plugin"

export default tool({
  description: "Query the project database",
  args: {
    query: tool.schema.string().describe("SQL query to execute"),
  },
  async execute(args) {
    return `Executed query: ${args.query}`
  },
})

Explicación:

  • description: Descripción de la herramienta, utilizada por el LLM para determinar si debe invocarla
  • args: Definición de parámetros (basada en Zod)
  • execute: Lógica de ejecución real

4. Múltiples herramientas en un solo archivo

Un archivo puede exportar varias herramientas, y cada una se nombrará automáticamente como:

<文件名>_<导出名>

import { tool } from "@opencode-ai/plugin"

export const add = tool({
  description: "Add two numbers",
  args: {
    a: tool.schema.number(),
    b: tool.schema.number(),
  },
  async execute(args) {
    return args.a + args.b
  },
})

export const multiply = tool({
  description: "Multiply two numbers",
  args: {
    a: tool.schema.number(),
    b: tool.schema.number(),
  },
  async execute(args) {
    return args.a * args.b
  },
})

Herramientas finales generadas:

  • math_add
  • math_multiply

5. Conflictos con herramientas integradas

Si el nombre de tu herramienta coincide con una herramienta integrada, sesobrescribirá la herramienta integrada。 

// 覆盖内置 bash 工具
export default tool({
  description: "Restricted bash wrapper",
  args: {
    command: tool.schema.string(),
  },
  async execute(args) {
    return `blocked: ${args.command}`
  },
})

Recomendación:

  • Evita conflictos de nombres
  • Si solo necesitas restringir capacidades, prioriza el uso depermissionla configuración

6. Definición de parámetros (Zod)

Los parámetros se definen mediante Zod Schema, con soporte para validación de tipos y descripciones:

args: {
  query: tool.schema.string().describe("SQL query"),
  limit: tool.schema.number().optional(),
}

También puedes usar Zod directamente:

import { z } from "zod"

export default {
  description: "Example tool",
  args: {
    name: z.string(),
  },
  async execute(args) {
    return `Hello ${args.name}`
  },
}

7. Contexto

La información de contexto se inyecta automáticamente cuando se ejecuta la herramienta:

export default tool({
  description: "Get project info",
  args: {},
  async execute(args, context) {
    const { agent, sessionID, directory, worktree } = context
    return `Agent: ${agent}, Dir: ${directory}`
  },
})<

Campos disponibles:

  • agent: Agente actual
  • sessionID: ID de sesión
  • messageID: ID de mensaje
  • directory: Directorio de trabajo actual
  • worktree: Directorio raíz de Git

8. Invocación de lenguajes externos (ejemplo con Python)

Puedes implementar la lógica de la herramienta en cualquier lenguaje, como Python.

1. Script de Python

# .opencode/tools/add.py
import sys

a = int(sys.argv[1])
b = int(sys.argv[2])

print(a + b)

2. Encapsulamiento de la herramienta

import { tool } from "@opencode-ai/plugin"
import path from "path"

export default tool({
  description: "Add two numbers using Python",
  args: {
    a: tool.schema.number(),
    b: tool.schema.number(),
  },
  async execute(args, context) {
    const script = path.join(context.worktree, ".opencode/tools/add.py")
    const result = await Bun.$`python3 ${script} ${args.a} ${args.b}`.text()
    return result.trim()
  },
})

Este enfoque es adecuado para:

  • Cadenas de herramientas Python existentes
  • Invocar análisis de datos / modelos de IA
  • Ejecutar tareas de cálculo complejas

9. Mejores prácticas

  • Las descripciones de las herramientas deben ser claras para ayudar al LLM a elegir correctamente
  • Diseña los parámetros de la forma más simple y clara posible
  • Evita efectos secundarios (a menos que sean explícitamente necesarios)
  • Prioriza el control de operaciones de riesgo mediante permission
  • Las herramientas deben centrarse en una única responsabilidad
Otras extensiones