工具与集成

内置工具（Built-in Tools）

默认全部 enabled，通过 Agent系统中的 permission 字段控制。

工具	说明
`bash`	执行 shell 命令
`edit`	精确字符串替换修改已有文件
`write`	创建新文件/覆盖已有文件（受 `edit` 权限位控制，`edit`/`write`/`apply_patch` 共用一个权限键）
`read`	读文件，支持指定行范围
`grep`/`glob`	内容搜索/文件模式匹配，底层用 ripgrep，默认遵循 `.gitignore`（可用项目根 `.ignore` 文件反向放行）
`lsp`（实验特性）	需 `OPENCODE_EXPERIMENTAL_LSP_TOOL=true`，支持 goToDefinition/findReferences/hover/documentSymbol 等
`apply_patch`	应用 patch/diff，同样受 `edit` 权限位控制
`skill`	加载 `SKILL.md` 并注入对话，对应 Agent系统的 Skill 机制
`todowrite`（+`todoread`）	管理任务清单，子 Agent 默认禁用，可手动开启
`webfetch`	抓取网页内容（检索指定 URL）
`websearch`	联网搜索（基于 Exa AI），仅当使用 OpenCode 官方 Provider 或设置 `OPENCODE_ENABLE_EXA=1` 才可用，无需自备 API key
`question`	执行中主动向用户提问（带 header/选项，支持多问题批量回答）

websearch 用于发现信息，webfetch 用于抓取已知 URL 的内容——这个区分与 Claude Code 的 WebSearch/WebFetch 分工完全一致。

自定义工具（Custom Tools）

在配置目录定义自己的函数供 LLM 调用，可执行任意代码（也可通过 Plugin 的 tool hook 注册，见下）。

MCP（Model Context Protocol）

MCP server 一旦启用，其工具与内置工具一视同仁地暴露给 LLM
注意事项：MCP 会占用上下文（尤其 GitHub MCP 之类工具多的服务器易超限），官方建议谨慎选用
配置在 opencode.json 的 mcp 字段，每个 server 一个唯一 key

Local（本地）

{
  "mcp": {
    "my-local-mcp-server": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": true,
      "environment": {"MY_ENV_VAR": "value"}
    }
  }
}

选项：type(必填)、command(必填数组)、cwd、environment、enabled、timeout(默认 5000ms)。

Remote（远程）

{
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "headers": {"Authorization": "Bearer MY_API_KEY"}
    }
  }
}

支持 OAuth 自动处理：检测 401 → 走 Dynamic Client Registration (RFC 7591) → 安全存储 token（~/.local/share/opencode/mcp-auth.json）。也支持预注册 client credentials，或 oauth: false 关闭自动探测改用 API key。管理命令：opencode mcp auth/list/logout/debug。

组织级远程默认值

组织可通过 .well-known/opencode 端点分发默认 MCP 配置（可设为默认禁用，用户按需 opt-in），本地配置覆盖远程默认值。

精细管理

全局禁用某 MCP 工具："tools": {"my-mcp-foo": false}，支持 glob "my-mcp*": false
仅特定 Agent 启用：先全局禁用，再在该 Agent 的 tools 字段里单独 true

官方文档给出的示例 MCP

Sentry（mcp.sentry.dev）、Context7（文档检索）、Grep by Vercel（GitHub 代码片段搜索）。

LSP Servers

内置常见语言 LSP，用于代码智能（跳转定义、引用查找等），可在 opencode.json 的 lsp 字段配置/禁用
与实验性 lsp 工具（上面的表格）配合，为 Agent 提供代码理解能力

Formatters

formatter 配置项管理语言特定的代码格式化工具，默认关闭需显式开启（formatter: true），可禁用内置或添加自定义 formatter。

Plugins（插件系统）

加载来源：

本地文件：.opencode/plugins/（项目级）、~/.config/opencode/plugins/（全局）
npm 包：opencode.json 的 plugin 数组，启动时用 Bun 自动安装并缓存到 ~/.cache/opencode/node_modules/

加载顺序（全部加载，hooks 按序执行）：全局配置 → 项目配置 → 全局插件目录 → 项目插件目录。

插件结构：JS/TS 模块，导出一个函数，接收 {project, client, $, directory, worktree}，返回 hooks 对象。$ 是 Bun 的 shell API，client 是 SDK client。

依赖管理：在配置目录放 package.json，OpenCode 启动时自动 bun install。

可订阅事件（节选）：

Tool：tool.execute.before/tool.execute.after
Session：session.created/session.idle/session.compacted/session.error 等
Permission：permission.asked/permission.replied
Shell：shell.env（可给所有 shell 执行注入环境变量）
还有 File/LSP/Message/TUI/Command 等事件类别

典型用例：发通知（session.idle 时 osascript 弹通知）、.env 读取保护（拦截 tool.execute.before 里 read 工具访问 .env）、通过插件注册自定义工具（用 @opencode-ai/plugin 的 tool() helper）、结构化日志（client.app.log() 而非 console.log）、自定义 Compaction 提示词（experimental.session.compacting hook，可替换或追加压缩上下文）。

若插件工具与内置工具同名，插件工具优先。

SDK

Type-safe JS client，用于以编程方式与 OpenCode server 交互（Sessions/Files/TUI/Auth/Events/Config 等 API 全覆盖），支持结构化输出（JSON Schema）。

Server（HTTP API）

opencode serve/opencode web 暴露的 HTTP 接口，涵盖 Global/Project/Path & VCS/Instance/Config/Provider/Sessions/Messages/Commands/Files/Tools(实验性)/LSP/Formatters/MCP/Agents/Logging/TUI/Auth/Events/Docs 等资源族，是构建自定义客户端或与 CI 集成的基础。

关联

索引 — 返回总索引
Agent系统 — 工具通过 permission 被 Agent 门控
权限与安全 — 权限规则的完整语法与优先级
对比Claude-Code — 工具/MCP/插件体系对照

来源

https://opencode.ai/docs/{tools,custom-tools,mcp-servers,lsp,plugins,sdk,server,formatters}.mdx（dev 分支）。整理：赵卫国 2026-07-07。

Wiki AI

目录

OpenCode 工具与集成