Outils personnalisés OpenCode

Les outils personnalisés vous permettent d'étendre les capacités d'OpenCode, en permettant au LLM d'appeler des fonctions que vous définissez pendant les conversations, et de mettre ainsi en œuvre des opérations complexes telles que des requêtes de base de données, l'exécution de scripts et des appels d'API.

Ces outils fonctionnent avec des outils intégrés (tels queread、write、bash)

Les outils personnalisés sont la capacité d’extension centrale d’OpenCode, faisant passer le LLM de la simple génération de code à l’exécution de tâches.

En concevant correctement les outils, vous pouvez créer :

  • Pipelines de développement automatisés
  • Assistants de code intelligents
  • Systèmes AI Ops
  • Plateformes d’outils IA internes à l’entreprise

1. Que sont les outils personnalisés ?

Un outil personnalisé est essentiellement une interface de fonction que le LLM peut appeler de manière proactive pendant l’exécution et dont il peut obtenir le résultat.

Cas d’usage typiques :

  • Interroger des bases de données (SQL / NoSQL)
  • Appeler des API internes
  • Exécuter des scripts (Python / Shell)
  • Lire l’état du système ou les informations d’environnement
  • Encapsuler une logique métier complexe

Vous pouvez le voir comme :Un mécanisme de plugin qui donne à l’IA des capacités d’exécution。

2. Emplacement de stockage des outils

OpenCode charge automatiquement les outils depuis les répertoires suivants :

  • Niveau projet :.opencode/tools/
  • Niveau global :~/.config/opencode/tools/

Le nom de fichier est le nom de l’outil (c’est crucial).

3. Définition de base d’un outil (recommandé)

Utilisertool()Les fonctions d’assistance assurent la sécurité de type et la validation des paramètres.

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}`
  },
})

Explication :

  • description: Description de l’outil, utilisée par le LLM pour déterminer s’il faut l’appeler
  • args: Définition des paramètres (basée sur Zod)
  • execute: Logique d'exécution réelle

4. Plusieurs outils dans un seul fichier

Un seul fichier peut exporter plusieurs outils, et chaque outil est automatiquement nommé comme suit :

<文件名>_<导出名>

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
  },
})

Les outils finaux générés :

  • math_add
  • math_multiply

5. Conflits avec les outils intégrés

Si le nom de votre outil est identique à celui d'un outil intégré, ilremplacera l'outil intégré。 

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

Recommandation :

  • Évitez les conflits de nommage
  • Si vous avez seulement besoin de restreindre les capacités, préférez utiliserpermissionconfiguration

6. Définition des paramètres (Zod)

Les paramètres sont définis à l'aide de Zod Schema, prenant en charge la validation de type et les descriptions :

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

Vous pouvez également utiliser directement Zod :

import { z } from "zod"

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

7. Contexte

Lorsqu'un outil s'exécute, des informations de contexte sont automatiquement injectées :

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

Champs disponibles :

  • agent: Agent actuel
  • sessionID: ID de session
  • messageID: ID du message
  • directory: Répertoire de travail actuel
  • worktree: Répertoire racine Git

8. Appel de langages externes (exemple en Python)

Vous pouvez implémenter la logique d'un outil dans n'importe quel langage, comme Python.

1. Script Python

# .opencode/tools/add.py
import sys

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

print(a + b)

2. Encapsulation d'outil

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()
  },
})

Cette approche convient pour :

  • Chaînes d'outils Python existantes
  • Appel à des modèles d'analyse de données / d'IA
  • Exécution de tâches de calcul complexes

9. Bonnes pratiques

  • Les descriptions d'outils doivent être claires pour aider le LLM à choisir correctement
  • Concevoir des paramètres aussi simples et clairs que possible
  • Éviter les effets secondaires (sauf si clairement nécessaires)
  • Préférer contrôler les opérations risquées via une autorisation
  • Les outils doivent se concentrer sur une seule responsabilité
Autres extensions