---
title: "OpenCode 에이전트 주입 토큰 구조 분석 및 최적화 가이드"
date: 2026-09-22
model: deepseek-flash
category: setups
summary: "OpenCode 에이전트의 시스템프롬프트, 규칙 파일, MCP 도구, 네이티브 도구 등 답변 전 주입되는 모든 토큰의 구조를 분석하고, 실제 측정값을 기반으로 최적화하는 방법을 상세히 정리한다."
tags: opencode,token,context,optimization,mcp,tool-schema,system-prompt
---

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

## 핵심 결론

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

| 구분 | Before | After | 절감 |
|------|--------|-------|------|
| 시스템 프롬프트 | ~5,865 tok | ~5,865 tok | - (하드코딩) |
| 규칙 파일 | ~1,612 tok | ~1,612 tok | - |
| 도구 스키마 | ~2,400 tok | ~2,400 tok | - |
| **고정 주입 합계** | **~9,877 tok** | **~9,877 tok** | - |

> 오픈코드는 바이너리가 하드코딩이라 시스템프롬프트/도구를 직접 줄이기 어렵다. 대신 규칙 파일과 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)

| 파일 | 크기 | 토큰 | 내용 |
|------|------|------|------|
| `.clinerules` | 1,860 bytes | ~1,306 tok | 자동 실행 에이전트 규칙, 웹검색 상세 규칙, 날씨 조회 규칙, 차트 생성 규칙 |
| `.instructions.md` | 551 bytes | ~306 tok | 로컬 AI 개발 환경(Ollama/MTP 서버 정보), 행동 강령, 작업 순서 |
| **합계** | **2,411 bytes** | **~1,612 tok** | |

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

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

| 도구 | 용도 |
|------|------|
| bash | 쉘 명령 실행 |
| read | 파일 읽기 |
| edit | 파일 편집(문자열 치환) |
| write | 파일 쓰기 |
| grep | 정규식 검색 |
| glob | 파일 패턴 매칭 |
| compress | 대화 컨텍스트 압축 |
| question | 사용자에게 질문 |
| task | 서브에이전트 호출 |
| skill | 스킬 로드 |
| webfetch | URL 콘텐츠 가져오기 |
| todowrite | 작업 목록 관리 |

### 1-4. MCP 도구

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

**직접 연결 (opencode.json):**

| 서버 | 용도 | 활성 |
|------|------|------|
| proxy | mcp-proxy-supervisor.sh 경유 다중 서버 | Yes |
| tavily | 웹 검색 (원격) | Yes |
| weather | 날씨 조회 (wttr-mcp-server) | Yes |
| browseros | 브라우저 제어 (127.0.0.1:9201) | Yes |

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

| 서버 | 도구 수 | Lazy |
|------|---------|------|
| playwright | 20+ | Yes |
| ts (Token Savior) | 10+ | Yes |
| filesystem | 10+ | Yes |
| code-review-graph | 9 | Yes |
| smart-context | 15+ | Yes |
| web-search | 2 | Yes |
| weather | 1 | Yes |

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

### 1-5. tool-slim 플러그인

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

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

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

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

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

| 구분 | 토큰 | 비율 |
|------|------|------|
| 시스템 프롬프트 | ~5,865 | 5.3% |
| 규칙 파일 | ~1,612 | 1.5% |
| 도구 스키마 | ~2,400 | 2.2% |
| 대화 히스토리 | ~101,200 | 91.5% |
| **합계** | **~110,500** | **100%** |

- 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 환경 정보

**절감 전략:**

| 전략 | 예상 절감 | 난이도 |
|------|-----------|--------|
| 불필요 규칙 삭제 (미사용 규칙 분리) | 200~500 tok | 하 |
| 영어로 변환 (한국어 1.1자/tok → 영어 4.5자/tok) | 50~150 tok | 중 |
| 반복 내용 제거 | 50~100 tok | 하 |

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

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

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

**현재 MCP 도구 스키마 추정:**

| 서버 | 추정 도구 수 | 추정 스키마 크기 |
|------|-------------|-----------------|
| playwright | ~20 | ~4,000 tok |
| ts (Token Savior) | ~10 | ~2,000 tok |
| filesystem | ~10 | ~1,500 tok |
| code-review-graph | ~9 | ~1,200 tok |
| smart-context | ~15 | ~3,000 tok |
| web-search | ~2 | ~300 tok |
| weather | ~1 | ~100 tok |

**비활성화 대상 후보:**

| 서버 | 사용 빈도 | 비활성화 시 절감 |
|------|-----------|-----------------|
| code-review-graph | 매우 낮음 | ~1,200 tok |
| smart-context | 낮음 | ~3,000 tok |
| playwright | 낮음 | ~4,000 tok |
| filesystem | 중간 | ~1,500 tok |

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

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

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

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

```javascript
// 현재 설정
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`):**

```json
"compaction": {
  "auto": true
}
```

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

**히스토리 절감 전략:**

| 전략 | 효과 | 비용 |
|------|------|------|
| 새 세션 시작 (/new) | 즉시 0으로 리셋 | 없음 |
| compaction.auto 유지 | 장기 세션에서 자동 관리 | MiMo 호출 비용 |
| 수동 압축 (compress 도구) | 필요 시점에 선택적 압축 | 없음 |

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

### 3-5. Direct MCP vs Proxy 비교

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

| 구조 | 장점 | 단점 |
|------|------|------|
| **Direct** (현재 opencode.json 4개) | 지연 최소, 안정적 | 서버별 관리 필요 |
| **Proxy** (mcp-proxy.json 7개) | 통합 관리, lazy 로드 | 중간 계층 오버헤드 |

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

## 4. 주의사항

### 4-1. 변경 전 필수 확인

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

### 4-2. 변경 후 필수 조치

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

### 4-3. 복구 방법

| 변경 | 복구 |
|------|------|
| 규칙 파일 수정 | 백업에서 복원 |
| MCP 서버 비활성화 | `enabled: true`로 되돌리기 |
| tool-slim 절단 길이 변경 | 원래 값으로 되돌리기 |

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

| 구분 | OpenCode | Hermes |
|------|----------|--------|
| 시스템 프롬프트 | 바이너리 하드코딩 (수정 불가) | SOUL.md 파일 (수정 가능) |
| 도구 비활성화 | MCP 서버 단위 | toolset 단위 |
| 규칙 파일 | .clinerules + .instructions.md | SOUL.md + memories/ |
| 스킬 시스템 | skill 도구로 로드 | 8개 활성 스킬 (자동 주입) |
| compaction | 자동 (MiMo 위임) | 수동 설정 가능 |
| 고정 주입 | ~9,877 tok | ~10,967 tok |

## 5. 체크리스트

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

---

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