自定义工具

自定义工具是模型可调用的函数。定义文件使用 JavaScript 或 TypeScript，但函数可以调用其他语言脚本；执行能力由实现本身决定，不局限于生成文本。

位置与工具名

项目工具放在 .opencode/tools/，全局放在 ~/.config/opencode/tools/。默认导出的工具使用文件名，例如 database.ts 对应 database；命名导出使用 <filename>_<exportname>，例如 math.ts 中的 add 对应 math_add。

同名自定义工具优先于内置工具。除非有意替换，否则避免使用 bash、read 等内置名称；只想禁止某项能力时使用 permission。

参数与执行

使用 @opencode-ai/plugin 的 tool() helper，tool.schema 基于 Zod，定义可校验的参数：

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

export default 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).toString()
  },
})

也可直接导入 Zod，返回包含 description、args、execute 的对象。schema 校验参数形状，不会自动保证查询、命令或外部 API 的业务安全，应在实现中继续检查。

执行上下文

execute(args, context) 可读取 agent、sessionID、messageID、directory 与 worktree。directory 是会话工作目录，worktree 是 Git worktree 根目录，两者不一定相同。

工具需要定位项目内脚本时，应明确以哪个目录为基准，不要依赖启动插件时恰好所在的位置。

调用其他语言

官方 Python 示例由 TS 工具通过 Bun.$ 启动 python3，用 path.join(context.worktree, ...) 定位脚本，读取文本输出后返回。相应语言运行时仍必须可用，定义工具并不会自动安装 Python。

该示例的 TypeScript schema 接受 number，而 Python 用 int() 处理参数，直接传入小数可能不符合脚本预期。实际工具应保持 schema 与被调用程序的输入约定一致，不把教学示例当成对全部数值有效的实现。

依赖与权限

需要外部 npm 包时，在配置目录声明依赖，OpenCode 启动时安装，见插件依赖。工具名称可以用 permission 的模式匹配控制，包括自定义和 MCP 工具。

上线使用前检查参数边界、错误传播、输出内容、运行目录和实际外部影响。本页代码是工具定义示例，并不表示已在你的环境安装依赖或运行。