OpenCode カスタムツール

カスタムツール（Custom Tools）を使用すると、OpenCode の機能を拡張し、LLM が対話中にあなたが定義した関数を呼び出して、データベースクエリ、スクリプト実行、API 呼び出しなどの複雑な操作を実現できます。

これらのツールは内蔵ツール（例：read、write、bash）と連携して、完全な自動化開発能力体系を構築します。

カスタムツールは OpenCode の中核となる拡張機能であり、LLM をコード生成のみから、タスクを実行できるレベルへと引き上げます。

ツールを適切に設計することで、以下を構築できます：

自動化開発パイプライン
インテリジェントコードアシスタント
AI 運用保守システム
企業内 AI ツールプラットフォーム

一、カスタムツールとは

カスタムツールは本質的に関数インターフェースであり、LLM は実行中にそれを能動的に呼び出して実行結果を取得できます。

代表的な利用シーン：

データベースのクエリ（SQL / NoSQL）
内部 API の呼び出し
スクリプトの実行（Python / Shell）
システム状態や環境情報の読み取り
複雑なビジネスロジックのカプセル化

次のように理解できます：AI に実行能力を持たせるプラグインメカニズム。

二、ツールの保存場所

OpenCode は以下のディレクトリ内のツールを自動的に読み込みます：

プロジェクトレベル：.opencode/tools/
グローバルレベル：~/.config/opencode/tools/

ファイル名がそのままツール名になります（非常に重要）。

三、基本ツール定義（推奨方法）

使用tool()ヘルパー関数を使用すると、型安全性とパラメータ検証機能が得られます。

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

説明：

description：ツールの説明。LLM が呼び出すかどうかの判断に使用
args：パラメータ定義（Zod ベース）
execute：実際の実行ロジック

四、単一ファイルでの複数ツール

1つのファイルで複数のツールをエクスポートでき、各ツールは自動的に次のように命名されます：

<文件名>_<导出名>

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

最終的に生成されるツール：

math_add
math_multiply

五、内蔵ツールとの競合

ツール名が内蔵ツールと同じ場合、内蔵ツールを上書きします。

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

推奨事項：

命名の競合を避ける
単に機能を制限するだけの場合は、優先的に使用permission設定

六、パラメータ定義（Zod）

パラメータは Zod Schema で定義され、型検証と説明をサポートします：

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

また、Zod を直接使用することもできます：

import { z } from "zod"

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

七、コンテキスト

ツール実行時にはコンテキスト情報が自動的に注入されます：

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

利用可能なフィールド：

agent：現在のエージェント
sessionID：セッション ID
messageID：メッセージ ID
directory：現在の作業ディレクトリ
worktree：Git ルートディレクトリ

八、外部言語の呼び出し（Python 例）

ツールのロジックは任意の言語で実装できます。例：Python。

1、Python スクリプト

# .opencode/tools/add.py
import sys

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

print(a + b)

2、ツールのラッピング

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

この方法は以下に適しています：

既存の Python ツールチェーン
データ分析 / AI モデルの呼び出し
複雑な計算タスクの実行

九、ベストプラクティス

ツールの説明を明確にし、LLM が正しく選択できるようにする
パラメータはできるだけシンプルで明確に設計する
副作用を避ける（明確に必要な場合を除く）
リスクのある操作は、優先的に permission を介して制御する
ツールは単一責任に集中する

その他の拡張