OpenCode Plugin의 경계 — 화면에서 숨긴 입력은 기록에도 남을까
OpenCode에서 사용자 정의 명령 입력을 숨기려던 사례를 통해 모델 입력·대화 저장·TUI 표시의 경계를 나누고, 플러그인 채택 전에 무엇을 검증해야 하는지 살펴본다.
관련: 제품 선택은 AI 코딩 도구 지형도 · 이동 경험은 얇은 하네스로 이동한 기록 · 실행·설정 참조는 devkit OpenCode 치트시트
OpenCode는 기본적인 코딩 에이전트 UX를 제공하면서 Plugin으로 동작을 확장할 수 있는 도구다. 처음에는 이 확장성이 “원하는 화면이나 자동화를 쉽게 붙인다”는 뜻으로 보인다. 그러나 실제로 UI를 조금 바꾸려다 보면 모델에 보낸 것, 저장한 것, 화면에 그린 것이 같은 데이터는 아니다라는 경계를 만나게 된다.
이 글의 출발점은 긴 사용자 정의 명령이다. 반복 작업 지침을 명령으로 빼면 입력은 짧아지지만, 확장된 명령 본문이 TUI에서 사용자 메시지처럼 길게 보일 수 있다. 내가 원한 것은 그 본문을 모델에는 보내되 화면에서는 접어 두는 것이었다.
기본 UX 위의 확장이기 때문에 경계가 생긴다
OpenCode는 요청에서 탐색·수정·검증까지 이어지는 기본 루프를 가진다. Plugin은 빈 실행기를 만드는 부품이라기보다, 이미 동작하는 제품의 특정 시점에 개입하는 확장점이다.
1
2
3
4
5
6
7
8
9
10
사용자 명령
↓ 확장·전처리
모델에 보낼 입력
↓ 모델·도구 호출 루프
대화·도구 결과
├─ 저장·내보내기 경로
└─ 화면 렌더링 경로
Plugin은 이 흐름의 지원되는 지점에 개입한다.
각 경로가 같은 필드·같은 필터를 쓴다고 가정하지 않는다.
위 화살표는 입력·결과의 전달이고, 저장과 표시의 두 가지 분기는 서로 다른 소비 경로다. 어느 한쪽을 바꾸는 필드가 다른 쪽에서도 해석된다면 화면 조정이 기록 손실로 이어질 수 있다.
Claude Code처럼 바로 쓸 수 있는 터미널 에이전트 경험을 원하면서 여러 Provider와 설정을 조정하려는 경우 OpenCode가 자연스러운 후보다. 반대로 최소 core 위에 도구·UI·메모리를 직접 조립하려면 Pi 같은 접근이 더 맞을 수 있다. 이 선택과 별개로, 확장을 지원한다는 사실은 내부 표현을 마음대로 바꿔도 안전하다는 보장이 아니다.
사례: 명령 본문에 synthetic을 표시한다면
2026년 7월 살펴본 구현에서는 command.execute.before에서 명령이 만든 text part에 synthetic을 표시하면 TUI에서는 숨기고 모델 입력은 유지하는 경로가 있었다. 당시의 최소 실험은 다음과 같다.
1
2
3
4
5
6
7
8
9
// 2026-07 구현을 대상으로 한 과거 실험.
// 현재 버전의 공개 API나 권장 설정으로 복사하지 않는다.
export const HideCommandInput = async () => ({
"command.execute.before": async (_input, output) => {
for (const part of output.parts) {
if (part.type === "text") part.synthetic = true;
}
},
});
여기서 바꾸는 대상은 일반 대화 전체가 아니라 명령 실행 과정에서 만들어진 text part다. 하지만 다른 Plugin이나 export 경로가 synthetic 항목을 제외한다면, 사람이 나중에 읽는 기록에서 명령 본문이 빠질 수 있다.
현재 공식 Plugin 문서의 소개만으로 이 내부 hook·필드 조합이 안정적인 계약이라고 확인할 수는 없다. 설치 버전의 타입·소스와 실제 내보내기 결과를 함께 봐야 한다. 과거에 동작한 코드를 현재 지원 기능처럼 소개하지 않는 이유다.
화면만 바꾸려면 세 계약을 따로 검사한다
| 경계 | 확인할 것 | 실패 예 |
|---|---|---|
| 모델 입력 | 원래 명령의 지침·인자가 그대로 전달되는가 | 화면은 깨끗하지만 필요한 지침도 빠짐 |
| 대화 저장·export | 모델이 본 입력을 필요한 범위에서 복원할 수 있는가 | 화면에서 숨긴 항목을 로그에서도 제거 |
| TUI 표시 | 사용자가 원한 항목만 감추거나 접는가 | 오류·승인·일반 입력까지 사라짐 |
검증은 “Plugin이 로드됐다”에서 끝나지 않는다.
- 짧은 고유 문구가 있는 테스트용 명령을 만든다.
- 확장 전후 모델 입력에 그 문구와 인자가 유지되는지 확인한다.
- 화면에서 감추는 범위가 해당 명령에만 적용되는지 본다.
- export·세션 재개·다른 transcript 소비자에서도 필요한 입력이 보존되는지 확인한다.
- Plugin을 끄면 원래 흐름으로 돌아오는지 확인한다.
검사할 로그 자체에도 비밀과 비공개 프롬프트가 포함될 수 있으므로, 이 검증은 공개 가능한 테스트 입력으로 한다. UI에서 보이지 않는다는 사실을 데이터가 전송·저장되지 않는다는 보안 보장으로 해석하지 않는다.
Plugin을 어디에 둘지도 동작의 일부다
OpenCode는 프로젝트·전역 Plugin과 패키지 형태의 확장을 지원한다. 다만 발견 규칙과 설정 이름은 버전에 따라 달라진다.
현재 공식 문서에서는 .opencode/plugins/와 ~/.config/opencode/plugins/의 자동 발견, 설정의 plugins 항목, 별도 TUI Plugin 설정을 구분한다. 과거 plugin 배열이나 단일 파일 경로 예시를 그대로 옮기기 전에 설치 버전의 문서를 확인한다. 프로젝트 루트의 아무 plugins/ 폴더나 자동으로 읽는 것은 아니다.
선택 기준은 단순하다.
| 형태 | 적합한 경우 | 검토할 위험 |
|---|---|---|
| 프로젝트 로컬 | 특정 저장소에만 필요한 동작 | 저장소를 신뢰할 때 실행될 코드 |
| 개인 전역 | 모든 프로젝트에 적용할 안정된 행동 | 다른 작업에도 영향을 미치는 범위 |
| 패키지 | 재사용·버전 배포가 필요한 통합 | 의존성·업데이트·공급망 |
설치 위치·현재 명령은 공식 문서를 참조하고, 꼭 필요한 범위에서만 켠다. 전역 적용은 한 저장소의 편의를 모든 세션의 전제조건으로 바꾸는 일이기 때문이다.
확장의 가치는 기능 수보다 검증 비용으로 판단한다
기본 UX 안에서 내 작업 루프가 잘 돈다면 Plugin을 추가하지 않아도 된다. 반복 문제가 분명하고 공개 API로 해결되며, 업데이트 뒤 검증할 범위를 설명할 수 있을 때 확장을 채택한다.
이번 사례에서 요구사항은 “모델 입력은 유지, 화면은 간결, 기록은 보존”의 세 가지였다. 세 요구를 동시에 검증하지 못한다면, 내부 필드를 전역 수정하기보다 표시 기능을 기다리거나 명령 본문 자체를 정리하는 편이 안전하다.
OpenCode의 확장성은 완제품 UX를 버리고 전부 직접 만들라는 뜻이 아니다. 지원되는 확장점과 내가 책임질 내부 가정을 구분하는 것이 제품과 Plugin을 오래 함께 쓰는 기준이다.