Ch10. 플러그인 확장
JS/TS 플러그인 설치, file·session·tool·tui 등 라이프사이클 훅, @opencode-ai/plugin로 커스텀 도구 개발, @opencode-ai/sdk 타입 활용을 다룹니다.
핵심 요약
- 플러그인은
.opencode/plugins/(로컬) 자동 로드 또는plugin배열의 npm 패키지로 설치하는 JS/TS 모듈입니다. @opencode-ai/plugin의Plugin타입으로{ project, client, $, directory, worktree }컨텍스트를 받는 비동기 함수를 export합니다.file.edited·session.created·tool.execute.before/after·tui.*같은 라이프사이클 훅에 로직을 겁니다.tool()헬퍼로deploy같은 커스텀 도구를 정의하고,@opencode-ai/sdk의 OpenAPI 기반 타입으로 안전성을 확보합니다.- v1.3.0에서 Anthropic OAuth 플러그인이 제거되어 API 키·SSO 등 다른 인증 방식으로 마이그레이션해야 합니다.
플러그인은 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 | 세션 업데이트 |
커스텀 도구 플러그인
새로운 도구도 플러그인으로 추가합니다.
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에서 버전을 고정해 재현성을 지킵니다
- 최소 구성: 플러그인이 무분별하게 늘면 운영 비용이 커지니 꼭 필요한 것만 씁니다