Ch10. 플러그인 확장
플러그인 API, 훅 시스템, 커스텀 도구 개발
플러그인은 OpenCode를 팀/제품 환경에 맞게 확장하는 핵심 수단입니다. JavaScript/TypeScript 모듈로 라이프사이클 이벤트에 훅을 걸 수 있습니다.
플러그인 설치 방법
로컬 플러그인
.opencode/plugins/ (프로젝트) 또는 ~/.config/opencode/plugins/ (전역)에 JS/TS 파일을 배치하면 시작 시 자동 로드됩니다.
npm 플러그인
{
"plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}플러그인 API
플러그인은 컨텍스트 객체를 받는 비동기 함수를 export합니다.
import type { Plugin } from '@opencode-ai/plugin'
export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
return {
// 훅 구현
}
}사용 가능한 훅
| 훅 | 설명 |
|---|---|
file.edited | 파일 편집 후 |
file.watcher.updated | 파일 감시 업데이트 |
session.created | 세션 생성 |
session.compacted | 세션 압축 |
session.deleted | 세션 삭제 |
session.diff | 세션 diff |
session.error | 세션 오류 |
session.idle | 세션 유휴 |
session.status | 세션 상태 변경 |
session.updated | 세션 업데이트 |
| 훅 | 설명 |
|---|---|
tool.execute.before | 도구 실행 전 |
tool.execute.after | 도구 실행 후 |
message.part.updated | 메시지 일부 업데이트 |
message.updated | 메시지 업데이트 |
message.removed | 메시지 삭제 |
permission.asked | 권한 요청 |
permission.replied | 권한 응답 |
| 훅 | 설명 |
|---|---|
shell.env | 셸 환경 변수 |
lsp.client.diagnostics | LSP 진단 결과 |
lsp.updated | LSP 업데이트 |
tui.prompt.append | TUI 프롬프트 추가 |
tui.command.execute | TUI 커맨드 실행 |
tui.toast.show | TUI 토스트 표시 |
server.connected | 서버 연결 |
experimental.session.compacting | 세션 압축 중 |
커스텀 도구 플러그인
새로운 도구를 플러그인으로 추가할 수 있습니다.
import { tool, type Plugin } from '@opencode-ai/plugin'
export const CustomToolsPlugin: Plugin = async (ctx) => {
return {
tool: {
deploy: tool({
description: '프로덕션 배포 실행',
args: {
env: tool.schema.string(),
tag: tool.schema.string(),
},
async execute(args, context) {
const result = await ctx.$`deploy.sh ${args.env} ${args.tag}`
return `배포 완료: ${args.env} (${args.tag})`
},
}),
},
}
}SDK 패키지
@opencode-ai/sdk가 공식 SDK로 배포됩니다. OpenAPI 스펙 기반 TypeScript 타입이 포함되어 있어, 플러그인 개발 시 타입 안전성을 확보할 수 있습니다.
npm i @opencode-ai/sdkBreaking: Anthropic OAuth 플러그인 제거 (v1.3.0)
v1.3.0에서 Anthropic OAuth 플러그인이 제거되었습니다. 기존에 이 플러그인으로 인증하던 워크플로우는 다른 인증 방식(API 키, SSO 등)으로 마이그레이션해야 합니다.
주요 서드파티 플러그인
| 플러그인 | 설명 |
|---|---|
opencode-helicone-session | Helicone 옵저버빌리티 연동 |
@gitlab/opencode-gitlab-plugin | GitLab Duo 도구 통합 |
고급 팁
- 역할별 플러그인 분리: 도메인별 플러그인을 분리해 장애 범위를 줄입니다
- tool.execute.before 활용: 도구 실행 전 검증 로직을 삽입해 안전성 확보
- 버전 핀: 팀 표준 플러그인은 npm에서 버전 고정으로 재현성 유지
- 최소 구성: 무분별한 플러그인 증가는 운영 비용을 높이므로 최소한으로