建立自定義工具

Custom tools 是你寫給 LLM 呼叫的函式。它們和 OpenCode 內建的 read、write、bash、grep 等工具並列存在，適合把專案專有、重複出現、輸入輸出穩定的動作封裝成可控入口。

這一篇用 12 分鐘換什麼：你會知道什麼時候值得寫 custom tool、工具檔案放哪裡、工具名怎麼生成、多個工具怎麼匯出、引數 schema 怎麼寫、context 能拿到什麼，以及哪些安全邊界不能交給模型猜。

先判斷是否真的需要

不要把 custom tool 當成“更高階的 bash”。先按這條路徑判斷：

flowchart LR
    Need["一個動作反覆出現"] --> Builtin{"內建工具能解決?"}
    Builtin -->|能| UseBuiltin["用 read / grep / bash / edit"]
    Builtin -->|不能| External{"是外部通用系統?"}
    External -->|是| MCP["優先 MCP"]
    External -->|不是| Stable{"輸入輸出穩定?"}
    Stable -->|否| Prompt["繼續用提示詞或指令碼"]
    Stable -->|是| Custom["封裝 custom tool"]

    style UseBuiltin fill:#dcfce7,stroke:#22c55e
    style MCP fill:#dbeafe,stroke:#3b82f6
    style Custom fill:#fef3c7,stroke:#f59e0b,stroke-width:2px

適合封裝的動作：

查詢內部服務狀態。
讀取專案專有配置格式。
執行固定診斷指令碼並返回摘要。
呼叫公司內部 API 的只讀介面。
把一段穩定 shell / Python / Node 指令碼包裝成結構化工具。

不適合封裝的動作：一次性命令、危險刪除、生產釋出、資料庫寫入、萬能 shell wrapper、會返回大量日誌的指令碼。

工具一旦進入 OpenCode，就會成為模型可能呼叫的能力。能用 permission 控制內建工具，就不要靠覆蓋內建工具名來“限制”它。

1. 工具放在哪裡

工具定義必須是 TypeScript 或 JavaScript 檔案，但工具定義內部可以呼叫任何語言寫的指令碼。

位置	適合什麼
`.opencode/tools/`	專案級工具，只服務當前儲存庫，推薦從這裡開始
`~/.config/opencode/tools/`	全域性工具，影響所有專案，確認穩定後再放這裡

大多數專案先用 .opencode/tools/。這樣工具隨儲存庫一起演進，不會把一個專案的假設帶到其他專案。

2. 最小工具結構

最簡單的方式是使用 tool() helper，它提供型別安全和引數校驗。

.opencode/tools/project-info.ts

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

export default tool({
  description: "Return current project directory information",
  args: {},
  async execute(args, context) {
    return `directory=${context.directory}\nworktree=${context.worktree}`;
  },
});

文件名会变成工具名。上面这个文件会创建 project-info 工具。新手先从只读工具开始，确认调用链、输出格式和权限边界都稳定，再考虑写入或外部请求。

3. 一个文件导出多个工具

官方文档说明，一个文件可以导出多个工具。每个 export 会变成独立工具，名字是 <filename>_<exportname>。

例如 .opencode/tools/math.ts 里导出 add 和 multiply，OpenCode 会注册成 math_add 和 math_multiply。

如果工具共享同一组内部 helper，放在一个文件里更容易维护；如果职责不同，拆成多个文件更清楚。不要为了少建文件把无关工具塞到一起。

4. 参数 schema 要写给模型看

tool.schema 就是 Zod。参数越少、描述越具体，模型越不容易误用。

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

也可以直接导入 Zod，返回普通对象：

import { z } from "zod";

args: {
  param: z.string().describe("Parameter description"),
}

好的参数描述会写清边界，例如“仓库内相对路径”“只读 SQL”“不包含密钥”“只允许 staging 环境”。不要只写 query、path、name 这种模型无法判断风险的描述。

5. context 能拿到什么

工具会收到当前 session（会话）的上下文。官方示例里包括 agent、sessionID、messageID、directory 和 worktree。

context.directory 是 session 工作目录（用户启动 OpenCode 时所在的那个文件夹）。
context.worktree 是 Git worktree（工作树，简单理解为"这个仓库当前 checkout 的文件树根目录"——一个 Git 仓库可以同时有多个 worktree，每个对应一个分支）的根目录。

路径拼接优先基于 context.worktree 或 context.directory，不要假设用户总在项目根目录启动 OpenCode。

6. 调用 Python 或 Shell 脚本

工具定义必须是 TypeScript / JavaScript，但真实逻辑可以放到 Python、Shell 或其他语言脚本里。

核心模式是：工具定义负责 schema、路径和输出摘要，脚本负责实际业务逻辑。例如用 context.worktree 找到项目内脚本，再通过 Bun shell 调用：

const script = path.join(context.worktree, ".opencode/tools/add.py");
const result = await Bun.$`python3 ${script} ${args.a} ${args.b}`.text();
return result.trim();