Benutzerdefinierte Tools

Erstellen Sie Tools, die das LLM in opencode aufrufen kann.

Benutzerdefinierte Tools sind Funktionen, die Sie erstellen und die das LLM während Gesprächen aufrufen kann. Sie funktionieren neben den integrierten Tools von opencode wie read, write und bash.

Ein Tool erstellen

Tools werden als TypeScript- oder JavaScript-Dateien definiert. Die Tool-Definition kann jedoch Skripte aufrufen, die in jeder beliebigen Sprache geschrieben sind — TypeScript oder JavaScript wird nur für die Tool-Definition selbst verwendet.

Speicherort

Sie können wie folgt definiert werden:

• Lokal, indem Sie sie im Verzeichnis .opencode/tools/ Ihres Projekts ablegen.
• Oder global, indem Sie sie in ~/.config/opencode/tools/ ablegen.

Struktur

Der einfachste Weg, Tools zu erstellen, ist die Verwendung des tool()-Helpers, der Typsicherheit und Validierung bietet.

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) {
    // Your database logic here
    return `Executed query: ${args.query}`
  },
})

Der Dateiname wird zum Tool-Namen. Das obige Beispiel erstellt ein database-Tool.

Mehrere Tools pro Datei

Sie können auch mehrere Tools aus einer einzigen Datei exportieren. Jeder Export wird zu einem separaten Tool mit dem Namen <filename>_<exportname>:

import { tool } from "@opencode-ai/plugin"
 
export const add = tool({
  description: "Add two numbers",
  args: {
    a: tool.schema.number().describe("First number"),
    b: tool.schema.number().describe("Second number"),
  },
  async execute(args) {
    return args.a + args.b
  },
})
 
export const multiply = tool({
  description: "Multiply two numbers",
  args: {
    a: tool.schema.number().describe("First number"),
    b: tool.schema.number().describe("Second number"),
  },
  async execute(args) {
    return args.a * args.b
  },
})

Dadurch werden zwei Tools erstellt: math_add und math_multiply.

Namenskonflikte mit integrierten Tools

Benutzerdefinierte Tools werden nach Tool-Namen verschlüsselt. Wenn ein benutzerdefiniertes Tool denselben Namen wie ein integriertes Tool verwendet, hat das benutzerdefinierte Tool Vorrang.

Diese Datei ersetzt beispielsweise das integrierte bash-Tool:

import { tool } from "@opencode-ai/plugin"
 
export default tool({
  description: "Restricted bash wrapper",
  args: {
    command: tool.schema.string(),
  },
  async execute(args) {
    return `blocked: ${args.command}`
  },
})

Hinweis: Bevorzugen Sie eindeutige Namen, es sei denn, Sie möchten ein integriertes Tool absichtlich ersetzen. Wenn Sie ein integriertes Tool deaktivieren, aber nicht überschreiben möchten, verwenden Sie Berechtigungen.

Argumente

Sie können tool.schema verwenden, was einfach Zod (opens in a new tab) ist, um Argumenttypen zu definieren.

args: {
  query: tool.schema.string().describe("SQL query to execute")
}

Sie können Zod (opens in a new tab) auch direkt importieren und ein einfaches Objekt zurückgeben:

import { z } from "zod"
 
export default {
  description: "Tool description",
  args: {
    param: z.string().describe("Parameter description"),
  },
  async execute(args, context) {
    // Tool implementation
    return "result"
  },
}

Context

Tools erhalten Kontext über die aktuelle Sitzung:

import { tool } from "@opencode-ai/plugin"
 
export default tool({
  description: "Get project information",
  args: {},
  async execute(args, context) {
    // Access context information
    const { agent, sessionID, messageID, directory, worktree } = context
    return `Agent: ${agent}, Session: ${sessionID}, Message: ${messageID}, Directory: ${directory}, Worktree: ${worktree}`
  },
})

Verwenden Sie context.directory für das Arbeitsverzeichnis der Sitzung. Verwenden Sie context.worktree für das Stammverzeichnis des Git-Worktrees.

Beispiele

Ein Tool in Python schreiben

Sie können Ihre Tools in jeder beliebigen Sprache schreiben. Hier ist ein Beispiel, das zwei Zahlen mit Python addiert.

Erstellen Sie zunächst das Tool als Python-Skript:

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

Erstellen Sie dann die Tool-Definition, die es aufruft:

import { tool } from "@opencode-ai/plugin"
import path from "path"
 
export default tool({
  description: "Add two numbers using Python",
  args: {
    a: tool.schema.number().describe("First number"),
    b: tool.schema.number().describe("Second 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()
  },
})

Hier verwenden wir das Bun.$ (opens in a new tab)-Hilfsprogramm, um das Python-Skript auszuführen.