[opencode 12일 집중 — 터미널 네이티브 AI 코딩 에이전트 완전 정복] 12/12화: opencode 로컬 모델 완전 가이드 2026 — Ollama·에어갭·규제 환경 도입 체크리스트

이 글은 「opencode 12일 집중」 12일차(최종회)입니다.

어제 11일차에서는 멀티 세션·서브에이전트·Git 통합으로 협업 규모를 키우는 법을 다뤘습니다. 오늘은 시리즈의 마지막 퍼즐 — opencode 로컬 모델 연동, 에어갭 네트워크 구성, 그리고 금융·의료 같은 규제 산업에서 실제로 도입하기 위한 체크리스트를 정리합니다. 외부 API 키 없이, 사내 폐쇄망 안에서 AI 코딩 에이전트를 돌리고 싶다면 이 글이 출발점입니다.

오늘의 핵심 3가지

• Ollama + opencode — 로컬 GPU 하나로 AI 코딩 에이전트를 완전 자체 호스팅하는 설정법
• 에어갭 아키텍처 — 인터넷 차단 환경에서도 opencode를 운영하는 네트워크 토폴로지
• 규제 환경 도입 체크리스트 — 망분리·데이터 잔존·감사 로그까지 실무 점검 항목 10가지

왜 로컬 모델인가 — 클라우드 API의 한계

3일차에서 다뤘듯 opencode는 75개 이상의 프로바이더를 BYOK로 연결할 수 있습니다. 하지만 금융권 전산센터, 의료기관 EMR 시스템, 방산·공공기관 개발실처럼 외부 인터넷 접속 자체가 차단된 환경에서는 API 키가 아무리 많아도 소용없습니다. opencode 로컬 모델 구성이 필요한 이유가 여기에 있습니다.

로컬 모델의 장점을 정리하면 다음과 같습니다.

• 데이터 유출 원천 차단 — 프롬프트·코드·응답 모두 사내 네트워크를 벗어나지 않음
• API 비용 제로 — GPU 전력비만 발생, 토큰 과금 없음
• 지연 시간 예측 가능 — 외부 네트워크 상태와 무관하게 일정한 응답 속도
• 규제 감사 단순화 — 데이터 흐름 경로가 단일 호스트 또는 사내 LAN으로 한정

Ollama로 opencode 로컬 모델 연동하기

Ollama는 로컬 LLM 서빙 도구로, OpenAI 호환 API를 기본 제공합니다. opencode는 OpenAI 호환 엔드포인트를 지원하므로 설정 몇 줄이면 연결이 끝납니다.

1단계: Ollama 설치 및 모델 다운로드

# Ollama 설치 (macOS/Linux)
curl -fsSL https://ollama.com/install.sh | sh

# 코딩 특화 모델 다운로드 (권장: Qwen2.5-Coder 32B)
ollama pull qwen2.5-coder:32b

# 서버가 자동 시작되지 않았다면 수동 시작
ollama serve

모델 선택 기준은 단순합니다. VRAM 24GB(RTX 4090급)이면 32B 파라미터 모델을, 12GB(RTX 4070급)이면 14B 모델을, 8GB 이하이면 7B 모델을 선택하세요. 코딩 작업에는 일반 챗 모델보다 코드 파인튜닝 모델이 훨씬 낫습니다.

VRAM	추천 모델	파라미터	체감 품질
48GB+	qwen2.5-coder:72b-instruct-q4_K_M	72B	클라우드 API에 근접
24GB	qwen2.5-coder:32b	32B	실무 사용 가능
12GB	qwen2.5-coder:14b	14B	간단한 리팩터링·버그 수정
8GB	qwen2.5-coder:7b	7B	자동완성·단순 질의

2단계: opencode 설정 파일 작성

프로젝트 루트의 opencode.json에 Ollama 엔드포인트를 등록합니다.

{
  "provider": {
    "ollama-local": {
      "type": "openai",
      "api_key": "ollama",
      "base_url": "http://localhost:11434/v1"
    }
  },
  "model": {
    "full": {
      "provider": "ollama-local",
      "model": "qwen2.5-coder:32b"
    },
    "mini": {
      "provider": "ollama-local",
      "model": "qwen2.5-coder:7b"
    }
  }
}

핵심 포인트 세 가지입니다.

• type: "openai" — Ollama의 OpenAI 호환 API를 사용
• api_key: "ollama" — Ollama는 인증을 요구하지 않지만 opencode가 빈 값을 허용하지 않으므로 아무 문자열이나 넣습니다
• base_url에 /v1 경로를 반드시 포함 — 빠뜨리면 404 에러가 발생합니다

3단계: 연결 확인

# opencode 실행
opencode

# TUI에서 간단히 테스트
> 현재 디렉토리의 파일 목록을 알려줘

응답이 돌아오면 로컬 모델 연동이 완료된 것입니다. opencode run -p "hello"로 비대화형 테스트도 해보세요.

Ollama 너머 — 다른 로컬 서빙 옵션

Ollama가 가장 간편하지만 유일한 선택지는 아닙니다. 조직 규모와 요구사항에 따라 다른 도구도 고려할 수 있습니다.

도구	특징	적합한 상황
Ollama	원클릭 설치, OpenAI 호환 API 기본 제공	개인·소규모 팀, 빠른 시작
vLLM	높은 처리량, 배치 추론 최적화	다수 개발자가 동시 사용하는 사내 서버
llama.cpp (server)	극도로 가벼움, CPU 추론 가능	GPU 없는 환경, 임베디드
TGI (HuggingFace)	HuggingFace 생태계 통합	모델 커스터마이징·파인튜닝 조직

어떤 도구를 쓰든 opencode 쪽 설정은 동일합니다 — type: "openai"로 지정하고 해당 서버의 base_url만 바꾸면 됩니다. 이것이 BYOK 아키텍처의 힘입니다.

에어갭 아키텍처 — 완전 폐쇄망 구성

인터넷이 물리적으로 차단된 환경에서 opencode를 운영하려면 몇 가지 추가 준비가 필요합니다.

사전 준비: 오프라인 패키지 번들링

인터넷이 되는 스테이징 머신에서 필요한 모든 것을 미리 다운로드합니다.

# 1. opencode 바이너리 다운로드 (인터넷 되는 머신에서)
curl -fsSL https://opencode.ai/install.sh -o opencode-install.sh
# 또는 GitHub Releases에서 바이너리 직접 다운로드

# 2. Ollama 바이너리 + 모델 파일 준비
ollama pull qwen2.5-coder:32b
# 모델 파일 위치 확인 후 복사
ls ~/.ollama/models/

# 3. USB/내부 전송 매체로 폐쇄망 머신에 복사
# opencode 바이너리, ollama 바이너리, 모델 파일(blob) 일체

폐쇄망 머신에서의 구성

# Ollama 바이너리 설치 (수동 복사)
sudo cp ollama /usr/local/bin/
chmod +x /usr/local/bin/ollama

# 모델 파일을 Ollama 디렉토리에 배치
cp -r models/* ~/.ollama/models/

# Ollama 서버 시작 (외부 연결 차단 확인)
OLLAMA_HOST=127.0.0.1:11434 ollama serve

# opencode 바이너리 배치
sudo cp opencode /usr/local/bin/
chmod +x /usr/local/bin/opencode

# opencode 설정 (위의 opencode.json 동일)
opencode

에어갭 환경에서 주의할 점이 하나 더 있습니다. opencode의 자동 업데이트 기능이 외부 접속을 시도할 수 있으므로 환경 변수로 비활성화합니다.

# 자동 업데이트 비활성화
export OPENCODE_DISABLE_UPDATE_CHECK=1

사내 LAN 공유 토폴로지

GPU 서버 한 대에 Ollama를 올리고 여러 개발자가 공유하는 구성도 가능합니다.

# GPU 서버 (192.168.1.100)
OLLAMA_HOST=0.0.0.0:11434 ollama serve

# 각 개발자 워크스테이션의 opencode.json
{
  "provider": {
    "team-gpu": {
      "type": "openai",
      "api_key": "internal",
      "base_url": "http://192.168.1.100:11434/v1"
    }
  },
  "model": {
    "full": {
      "provider": "team-gpu",
      "model": "qwen2.5-coder:32b"
    }
  }
}

이 구성에서는 GPU 서버의 방화벽을 사내 IP 대역만 허용하도록 설정하는 것이 필수입니다.

규제 환경 도입 체크리스트 10가지

금융감독원 전자금융감독규정, 의료법 시행규칙, 공공기관 보안 지침 등 규제 산업에서 AI 코딩 에이전트를 도입할 때 점검해야 할 항목을 정리합니다. opencode 로컬 모델 구성이 이 요건들을 어떻게 충족하는지 함께 표기했습니다.

데이터 보호 영역

#	점검 항목	opencode 로컬 구성 대응
1	코드 외부 전송 차단 — 소스코드가 사외 서버로 나가지 않는가	Ollama 로컬 서빙 → 네트워크 트래픽 제로. 에어갭 시 물리적 보장
2	프롬프트 데이터 잔존 금지 — 입력 프롬프트가 외부에 저장되지 않는가	Ollama는 프롬프트를 디스크에 저장하지 않음. opencode 세션 로그는 로컬 ~/.opencode/에만 존재
3	모델 응답 캐시 관리 — 생성된 코드 조각이 제3자에게 학습 데이터로 재사용되지 않는가	로컬 모델 → 학습 데이터 재사용 경로 자체가 없음

네트워크·접근 통제 영역

#	점검 항목	opencode 로컬 구성 대응
4	망분리 준수 — 개발망과 인터넷망 간 데이터 이동이 통제되는가	에어갭 구성 시 완전 준수. LAN 구성 시 Ollama 바인드 IP 제한 + 방화벽 룰
5	접근 권한 관리 — 인가된 개발자만 AI 에이전트를 사용하는가	Ollama 앞단에 nginx 리버스 프록시 + Basic Auth 또는 mTLS 적용 가능
6	내부 시스템 연동 통제 — MCP 서버 등 확장 도구가 허용 범위를 넘지 않는가	9일차에서 다뤘듯 MCP 서버는 opencode.json에 명시적 등록 필요. 화이트리스트 방식

감사·로깅 영역

#	점검 항목	opencode 로컬 구성 대응
7	사용 이력 로깅 — 누가 언제 어떤 프롬프트를 보냈는지 기록하는가	opencode 세션 로그(~/.opencode/sessions/) + Ollama 요청 로그를 syslog로 포워딩
8	생성 코드 추적성 — AI가 생성한 코드를 식별하고 리뷰할 수 있는가	11일차의 Git 통합 — AI 변경분이 커밋 단위로 분리됨. /undo로 즉시 롤백 가능
9	로그 보존 기간 — 감사 증적이 규정 기간(보통 5년) 동안 보존되는가	세션 로그를 사내 로그 수집 시스템(ELK, Splunk 등)으로 포워딩하는 스크립트 별도 구성
10	비상 차단 — 문제 발생 시 AI 에이전트를 즉시 중단할 수 있는가	ollama stop 한 줄로 서빙 중단. opencode는 모델 연결 실패 시 자동 비활성화

금융IT 실무 적용 사례 — A 금융사의 도입 여정

어떤 카드사의 차세대 시스템 개발팀이 opencode 로컬 모델을 도입한 과정을 익명화하여 공유합니다.

배경: 전자금융감독규정상 소스코드의 외부 전송이 금지된 환경. 기존에는 AI 코딩 도구 사용 자체를 전면 차단하고 있었으나, 개발 생산성 격차가 벌어지면서 ‘사내 완결형’ 대안을 모색.

구성:

• GPU 서버(A100 80GB × 2) 1대에 vLLM으로 70B급 코딩 모델 서빙
• 개발자 워크스테이션 40대에서 opencode 클라이언트 사용
• opencode → vLLM 간 통신은 개발 VLAN 내부로 한정
• 모든 세션 로그를 사내 Splunk로 실시간 수집 — 감사 시 프롬프트·응답 전문 조회 가능

결과:

• 코드 리뷰 리드타임 30% 단축 (AI가 1차 패턴 검사를 수행)
• 보안 팀 승인까지 8주 소요 — 가장 오래 걸린 항목은 “프롬프트 잔존 검증”과 “모델 업데이트 절차 문서화”
• 도입 6개월 후 다른 3개 팀으로 확산

이 사례의 핵심 교훈은, 기술 구성보다 보안 팀과의 사전 협의가 더 오래 걸린다는 점입니다. 체크리스트 10가지를 미리 채워서 보안 심의에 들어가면 승인 기간을 크게 줄일 수 있습니다.

코드 미저장 정책 — AGENTS.md에 명시하기

규제 환경에서는 AI가 생성한 코드의 관리 정책을 AGENTS.md에 선언적으로 기록해두는 것이 좋습니다. 7일차에서 다뤘던 AGENTS.md의 규제 환경 확장 예시입니다.

# AGENTS.md — 규제 환경 확장 섹션

## 보안 정책
- 외부 API 호출 금지. 모든 LLM 추론은 사내 서버(192.168.x.x)를 사용한다.
- 고객 데이터(PII)가 포함된 파일은 프롬프트에 포함하지 않는다.
- 생성된 코드는 반드시 사람이 리뷰한 후 커밋한다.

## 감사 대응
- 이 프로젝트의 opencode 세션 로그 보존 기간: 5년
- 로그 포워딩 대상: siem.internal.company.com:514

이렇게 AGENTS.md에 정책을 명시하면 opencode가 세션 시작 시 이 규칙을 컨텍스트로 로드하므로, AI가 금지된 패턴의 코드를 생성할 확률이 줄어듭니다. 물론 AI의 자율 판단에만 의존하면 안 되고, CI/CD 파이프라인에 정적 분석 게이트를 함께 두는 것이 맞습니다.

성능 최적화 팁

로컬 모델은 클라우드 API 대비 응답 속도가 느릴 수 있습니다. 체감 성능을 올리는 실전 팁입니다.

• mini 모델 분리 — 위 설정처럼 full과 mini를 나눠 설정. 단순 질의는 7B가 처리하고, 복잡한 리팩터링만 32B가 담당
• 컨텍스트 길이 제한 — Ollama의 num_ctx 파라미터를 작업에 맞게 조절. 기본 4096이면 대부분 충분, 대규모 파일 분석 시만 8192~16384
• GPU 레이어 최적화 — ollama run --num-gpu 99로 가능한 모든 레이어를 GPU에 올림. 부분 오프로드(CPU+GPU 혼합)는 속도가 급격히 저하
• Plan 모드 활용 — 5일차에서 다뤘던 Plan 모드를 적극 사용. 읽기 전용 분석은 mini 모델로 빠르게 처리하고, 실제 코드 수정만 full 모델에 위임

# Ollama 모델 파라미터 커스터마이징 예시
# Modelfile 작성
cat << 'EOF' > Modelfile
FROM qwen2.5-coder:32b
PARAMETER num_ctx 8192
PARAMETER temperature 0.1
PARAMETER top_p 0.9
EOF

ollama create qwen-coder-custom -f Modelfile

temperature 0.1은 코딩 작업에 적합한 낮은 창의성 설정입니다. 코드 생성은 정확성이 우선이므로 높은 temperature는 오히려 해가 됩니다.

Gotcha 미니 코너 — Ollama 컨텍스트 윈도우 함정

Ollama의 기본 컨텍스트 윈도우는 2048 토큰입니다. opencode가 파일 내용 + 시스템 프롬프트 + 대화 이력을 합치면 이 제한을 금방 초과합니다. 초과 시 에러 메시지 없이 앞쪽 컨텍스트가 잘려나가 엉뚱한 응답이 돌아옵니다.

해결: 반드시 num_ctx를 명시적으로 설정하세요. Modelfile에서 지정하거나, Ollama API 호출 시 옵션으로 전달합니다. 코딩 작업이라면 최소 8192, 대규모 코드베이스 분석이라면 16384 이상을 권장합니다. 단, 컨텍스트가 길수록 VRAM 사용량이 비례해서 증가하므로 GPU 메모리와 균형을 잡아야 합니다.

12일 시리즈 총정리 — opencode 완전 정복 로드맵

12일간의 여정을 한 장의 표로 되돌아봅니다.

Phase	회차	핵심 주제	얻은 것
입문	1일차	opencode 개관·포지셔닝	왜 opencode인지 이해
	2일차	설치·첫 세션	5분 안에 동작하는 환경
	3일차	BYOK 모델 연결	비용 최적화된 프로바이더 선택
핵심	4일차	TUI 단축키	키보드 중심 고속 워크플로우
	5일차	Plan ↔ Build	안전한 코드 변경 루틴
	6일차	내장 툴	파일·셸·검색·LSP 통합 활용
	7일차	AGENTS.md	프로젝트 컨텍스트 설계
확장	8일차	커스텀 커맨드	반복 작업 자동화 템플릿
	9일차	MCP 연동	외부 도구·데이터 확장
	10일차	serve·run 자동화	CI/CD 파이프라인 통합
	11일차	멀티 세션·Git	팀 규모 협업
	12일차	로컬 모델·규제 환경	폐쇄망 자체 호스팅

시리즈를 마치며 — 도구는 선택이지만 방향은 필수

12일 동안 opencode라는 하나의 도구를 집중적으로 파헤쳤지만, 이 시리즈의 진짜 메시지는 도구 그 자체가 아닙니다.

AI 코딩 에이전트는 이미 선택의 문제가 아니라 적용 방법의 문제입니다. Claude Code, Cursor, Codex, 그리고 opencode — 도구는 계속 바뀌겠지만, “AI와 함께 코딩하는 워크플로우를 어떻게 설계할 것인가”라는 질문은 모든 개발 조직이 답해야 합니다.

opencode가 보여준 가치는 명확합니다.

• 벤더 락인 없음 — 모델이 바뀌면 설정 한 줄만 고치면 됩니다
• 오픈소스 투명성 — 코드가 어디로 가는지, AI가 무엇을 하는지 전부 감사 가능합니다
• 점진적 도입 — 오늘 배운 에어갭 구성처럼, 가장 보수적인 환경에서도 시작할 수 있습니다

1일차의 설치 한 줄에서 시작해 12일차의 에어갭 아키텍처까지 — 따라오신 여러분은 이미 opencode를 실무에 도입할 준비가 되었습니다. 이제 남은 건 opencode 한 번 치고 시작하는 것뿐입니다.

12일간 함께해 주셔서 감사합니다.

Photo by Tanhauser Vázquez R. on Pexels

---