Custom Tools

Name: OpenCode
Author: OpenCode

Tạo functions tùy chỉnh mà LLM có thể gọi — viết bằng TypeScript, JavaScript, hoặc bất kỳ ngôn ngữ nào.

Tổng quan

Custom Tools là functions bạn tạo ra mà LLM có thể gọi trong conversations. Chúng hoạt động song song với built-in tools như read, write, và bash.

Tools được định nghĩa bằng TypeScript/JavaScript, nhưng có thể gọi scripts viết bằng bất kỳ ngôn ngữ nào (Python, Bash, Ruby...).

Vị trí

Project: .opencode/tools/
Global: ~/.config/opencode/tools/

Tạo tool

Dùng helper tool() từ @opencode-ai/plugin:

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) {
    // Logic ở đây
    return `Executed: ${args.query}`
  },
})

Tên file trở thành tên tool. File database.ts → tool database.

Nhiều tools trong một file

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

Tạo 2 tools: math_add và math_multiply.

Arguments

Dùng tool.schema (Zod) để định nghĩa kiểu:

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

Hoặc import Zod trực tiếp:

import { z } from "zod"

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

Context

Tools nhận context về session hiện tại:

async execute(args, context) {
  const { agent, sessionID, messageID, directory, worktree } = context
  return `Agent: ${agent}, Dir: ${directory}`
}

context.directory — Thư mục làm việc của session
context.worktree — Git worktree root

Override built-in tools

Nếu custom tool trùng tên với built-in tool, custom tool được ưu tiên:

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

:::note Chỉ dùng unique names trừ khi bạn cố tình muốn override. Muốn disable built-in tool thì dùng permissions. :::

Ví dụ: Tool bằng Python

Bạn có thể viết tool bằng bất kỳ ngôn ngữ nào.

Script Python (.opencode/tools/add.py):

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

Tool definition (.opencode/tools/python-add.ts):

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

Dùng Bun.$ để chạy Python script.