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：实际执行逻辑

四、单文件多工具

一个文件可以导出多个工具，每个工具会自动命名为：

<文件名>_<导出名>

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

七、上下文（Context）

工具执行时会自动注入上下文信息：

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 控制风险操作
工具应聚焦单一职责