ARTICLE · 1342072

OpenCode 插件详解:界面、终端、行为全自定义

发布时间：2026-11-11 04:39:42 最近访问：2026-11-11 04:39:43

想自定义 OpenCode，插件是绕不开的入口：桌面端的界面、终端界面的长相、agent 的行为，全都能动。相比之下，MCP 只管"给 AI 递外部工具"，插件管的更多，能直接改 OpenCode 本身。很多人没注意，OpenCode V2 有 80 多个内部功能就是用插件 API 写的。所以别把插件当成高级玩法，它就是这套工具的"正经打开方式"。这篇不教你怎么写，带你把插件能改的地方一次盘清。

插件全景：Server、TUI、GUI、RPC 四个部分各管一摊

一个插件就是一个包（或一个目录），里面按位置分四个部分，各管一层：

my-plugin/├── index.ts   ← Server 部分：改行为，跑在后台服务里├── tui.tsx    ← TUI 部分：改终端界面├── gui.tsx    ← GUI 部分：改桌面端界面└── rpc.ts     ← 前后端之间的类型化契约

四个部分可以任意组合，只想改行为就只写 index.ts，只想在终端界面挂东西就只写 tui.tsx。装法也不复杂：扔进项目的 .opencode/plugins/ 目录就自动加载，或者登记在配置的 plugins 字段里；文件一保存就热重载，会话都不用重启。

下面按"能改什么"逐层看。

界面（GUI）：面板、设置页、代码块都能改

GUI 部分面向 OpenCode 桌面端（实验性 API，导出名 gui-experimental 里的 "experimental" 就是在提醒）：

侧边面板：会话旁边的面板里加自己的标签页，能拖动、能调宽、能记住开关状态；
设置页：在 Settings 里加一整页自己的配置界面，支持多语言文案；
窗口各处：命令面板和 / 菜单加命令、标题栏加按钮、输入框上方加状态 pill（比如挂一条当前分支的 PR 状态）、窗口底部加一条常驻信息条；
接管代码块：```csv 这样的代码块直接渲染成表格，还能给代码块加自定义按钮，比如"在终端里运行"；
接管链接：自定义协议、本地文件的点击行为都能自己处理；
原生能力：在桌面端的 main 进程里能加原生菜单，用上 Node 和 Electron 的全部本领。

终端界面（TUI）：状态栏、侧边栏、面板都能挂内容

TUI 部分管终端界面，能动的位置比想象中多：

Slot 挂载点：主页底部状态栏、侧边栏、输入框上下方等 9 个点位，插件往里塞自己的内容，五种插法，从"塞进去一条"到"整个接管"都行；
会话面板：命令一敲，旁边展开一整块自定义面板，宽度、焦点、全屏切换归宿主管，插件只管内容；
命令与页面：进命令面板、挂斜杠命令、绑快捷键，还能注册自己的页面路由；
对话框和 Toast：确认框、输入框、选择器都是现成的；
系统通知：会话跑完弹系统通知、配声音，终端缩在后台也不怕错过；
接管 Markdown 代码块：指定语言的代码块可以画成任意样子；
读会话数据：会话列表、消息、花费、状态都有现成接口；
跨会话存储：持久化，且多个终端实例之间自动同步。

小到一个按键的行为都能改，比如把 Tab 键换成自己的模型档位循环。

行为层（Server）：自定义工具、命令、Agent 与模型

Server 部分跑在后台服务里，凡是"改 OpenCode 行为"的口子都开在这里：

给 agent 加自定义工具和斜杠命令，把一套内部流程封装成一次函数调用或一条 /命令；
加 Agent、改 Agent、换默认 Agent，团队规范可以直接长在工具里；
增删 provider 和模型，统一管控团队里能用哪些模型；MCP 服务器的启停也能程序化管理；
接集成：OAuth、API key 的授权流程都有现成 API；
订阅事件：会话进度、权限请求、配置变化都能监听，拿来做自动化；
自带存储：按插件隔离的 JSON 存储，重启不丢。

再细一点的还有 skill、reference、VCS、worktree 这些域都能动。给 AI 接外部服务是 MCP 的活，改 OpenCode 本身是插件的活，两边不重叠。

前后端如何通信：插件架构的一根主线

看到这里你可能会问：界面部分改的是"长相"，数据从哪来？这就要说到 OpenCode 的架构了。它是标准的客户端-服务端结构：一个常驻后台服务管着会话、配置和所有插件，终端和桌面端只是三块不同的"屏幕"。

插件也顺着这个结构分成两半：Server 部分跟着后台服务跑，行为改一次，三端同时生效；TUI、GUI 部分跟着各自的界面跑，只管显示。前后端的通信有三条通道：

TUI → 服务：context.client 就是 OpenCode 的客户端，直接调后台服务的接口，连远程服务器也一样用；服务端的事件用 data.on 订阅，实时推到界面上。
GUI → 服务：同样有 ctx.client。要调用自己插件 Server 部分里的方法就走 RPC：rpc.ts 里定义一份类型化契约，server 实现、界面调用，参数和返回值全程有类型。
桌面端内部：Electron 主进程和窗口之间还有一条 Ipc 桥；插件和插件之间也能互相提供能力，A 插件定义契约，B 插件直接用。