OpenCode 에이전트 주입 토큰 구조 분석 및 최적화 가이드

핵심 결론

OpenCode는 매 요청마다 약 110,500 토큰이 입력된다. 그중 대화 히스토리가 91.5%를 차지하지만, 고정 주입(시스템프롬프트+규칙+도구 스키마)은 매번 재사용되는 기반이다. 고정 주입을 줄이면 prompt cache 히트율이 올라가고, 총 비용이 절감된다.

> 오픈코드는 바이너리가 하드코딩이라 시스템프롬프트/도구를 직접 줄이기 어렵다. 대신 규칙 파일과 MCP 서버 정리가 핵심 절감 지점이다.

1. 주입 구조 전체도

[시스템 프롬프트]  ~5,865 tok  (5.3%)  ← 바이너리 하드코딩
[규칙 파일]        ~1,612 tok  (1.5%)  ← .clinerules + .instructions.md
[도구 스키마]      ~2,400 tok  (2.2%)  ← 네이티브 + MCP
[대화 히스토리]  ~101,200 tok (91.5%)  ← 세션 누적
─────────────────────────────────────
합계            ~110,500 tok (100%)

1-1. 시스템 프롬프트 (~5,865 tok / ~23,458자)

OpenCode 바이너리(~/.opencode/bin/opencode, 184MB)에 하드코딩. 내용:

• 역할 정의: "You are opencode, an interactive CLI tool..."
• 톤/스타일: 간결, 마크다운, 이모지 금지, 4줄 이내 답변
• 도구 사용 정책: Tasktool 우선, 병렬 호출 권장
• 코드 스타일: 검색 우선순위, file_path:line_number 참조 패턴
• 작업 관리: TodoWrite 사용 규칙

이 스크립트는 직접 수정 불가 — 바이너리 재빌드 없인 변경 불가.

1-2. 규칙 파일 (~1,612 tok)

1-3. 네이티브 도구 (~12개)

OpenCode에 기본 탑재된 도구. MCP 없이 바로 사용 가능.

1-4. MCP 도구

opencode.json에 정의된 MCP 서버에서 제공하는 도구.

직접 연결 (opencode.json):

프록시 경유 (mcp-proxy.json, lazy 모드):

lazy 모드 동작: 브릿지 도구(tool_search, tool_describe, tool_call)만 미리 노출. 실제 서버 도구는 사용 시점에 로드.

1-5. tool-slim 플러그인

.config/opencode/plugins/tool-slim.js가 도구 설명을 절단:

• 도구 설명: 80자로 제한
• 파라미터 설명: 60자(최상위), 40자(중첩)

→ 도구 구분 단서가 사라져 모델의 도구 선택 실패를 유발할 수 있음.

2. 실제 측정값 (운영 환경 기준)

아래 수치는 opencode DB에서 최근 응답 기준으로 추출한 실제값이다.

• prompt caching 적용 시 시스템프롬프트+도구는 cache_read로 재사용 (~106,752 tok cache hit)
• 토크나이저: cl100k_base (OpenAI 호환)
• 한국어: ~1.1자/token, 영어: ~4.5자/token

3. 최적화 방법

3-1. 규칙 파일 다이어트 (즉시 적용 가능)

.clinerules와 .instructions.md는 사용자가 직접 편집 가능.

현재 구성:

• .clinerules (1,860 bytes): 자동 실행 에이전트 규칙 + 웹검색 + 날씨 + 차트
• .instructions.md (551 bytes): 로컬 AI 환경 정보

절감 전략:

주의사항:

• .instructions.md의 MTP 서버 주소(127.0.0.1:18081) 삭제 시 서버 연결 불능
• 차트 생성 규칙 삭제 시 chart-render 스킬 사용 불가
• 규칙 변경 후 캐시 리셋 필요 (세션 재시작)

3-2. MCP 서버 정리 (가장 큰 절감 지점)

mcp-proxy.json의 7개 서버 중 미사용 서버를 비활성하면 도구 스키마를 절감할 수 있다.

현재 MCP 도구 스키마 추정:

비활성화 대상 후보:

비활성화 방법: mcp-proxy.json에서 해당 서버 블록을 "enabled": false로 변경.

주의사항:

• playwright 비활성 시 브라우저 자동화 불가
• filesystem 비활성 시 로컬 파일 접근 MCP 경유 불가
• lazy 모드라 사용 시점에만 로드되지만, 도구 목록은 매번 주입됨
• 비활성화 전 해당 서버 도구 사용 이력 확인 필수

3-3. tool-slim 플러그인 조정

.config/opencode/plugins/tool-slim.js의 절단 길이를 늘리면 도구 구분력이 올라간다.

// 현재 설정
const MAX_DESC_CHARS = 80;      // 도구 설명
const MAX_PARAM_CHARS = 60;     // 파라미터 설명 (최상위)
const MAX_NESTED_PARAM = 40;    // 중첩 파라미터

// 제안: 도구 설명 120자로 확장
const MAX_DESC_CHARS = 120;

효과: 도구 설명의 키워드가 살아남아 모델의 도구 선택 정확도 향상.

주의사항:

• 절단 길이를 너무 늘리면 토큰 소모 증가
• 120~150자가 적정 범위
• 변경 후 debug 로그로 절단 동작 확인

3-4. 대화 히스토리 관리

히스토리가 91.5%를 차지하므로, 히스토리 관리가 총 토큰에 가장 큰 영향을 준다.

compaction 설정 (opencode.json):

"compaction": {
  "auto": true
}

• auto: true: 컨텍스트 창이 차면 자동으로 오래된 턴을 요약
• 요약은 MiMo(외부 모델)를 호출하므로 비용 발생

히스토리 절감 전략:

핵심: compaction은 "내용을 삭제"하는 것이 아니라 "오래된 턴을 요약으로 대체"한다. 총 내용량은 줄지 않지만, 주입 토큰 수는 줄어든다.

3-5. Direct MCP vs Proxy 비교

현재 proxy 서버를 경유하는 구조인데, 직접 연결로 전환하면 오버헤드를 줄일 수 있다.

권장: 미사용 proxy 서버 비활성화가 직접 연결 전환보다 우선.

4. 주의사항

4-1. 변경 전 필수 확인

1. 현재 사용 중인 MCP 도구 목록 확인: opencode 세션에서 각 MCP 서버 도구 사용 이력 검토
2. 규칙 파일 백업: .clinerules, .instructions.md 변경 전 백업
3. 테스트: 변경 후 간단한 작업으로 정상 동작 확인

4-2. 변경 후 필수 조치

1. 세션 재시작: 규칙/MCP 변경은 새 세션에서만 반영
2. 캐시 리셋: prompt cache가 이전 설정을 기억할 수 있음
3. 모니터링: 도구 선택 실패율 증가 여부 관찰

4-3. 복구 방법

4-4. 오픈코드 vs 헤르메스 비교

5. 체크리스트

• [ ] .clinerules에서 미사용 규칙 확인 및 정리
• [ ] .instructions.md에서 불필요 환경 정보 삭제
• [ ] mcp-proxy.json에서 미사용 서버 비활성화
• [ ] tool-slim.js 절단 길이 검토 (80→120자)
• [ ] 세션 재시작 후 정상 동작 확인
• [ ] 도구 선택 실패율 모니터링

운영자 환경 측정 기준 (opencode v1.x, cl100k_base 토크나이저, Linux). 개별 환경에 따라 수치가 달라질 수 있다.