온프레미스 OpenCode, 사내 개발팀의 구현 담당으로 쓸 만한가

사내 서버에서 오픈웨이트 모델을 돌리고 OpenCode로 코드를 수정하는 방식이 개발팀의 현실적인 선택지로 떠오르고 있다. 비용과 데이터 통제에는 장점이 있다. 다만 클라우드 모델처럼 바로 안정적인 결과를 내는지는 별개의 문제다. 이 글은 온프레미스 OpenCode가 구현 업무를 맡을 수 있는 조건과 어디까지 자동화해야 하는지를 살펴본다.

온프레미스 OpenCode가 맡는 역할은 무엇인가

OpenCode는 터미널에서 실행하는 오픈소스 AI 코딩 에이전트다. 현재는 데스크톱 앱과 IDE 확장으로도 사용할 수 있으며 특정 모델 제공업체에 고정되지 않는다. OpenCode 공식 문서는 Anthropic, OpenAI, Google 같은 외부 제공업체와 자체 OpenAI 호환 엔드포인트를 함께 설정할 수 있다고 설명한다.

사내에서 쓰려면 OpenCode와 모델 서버를 분리해서 생각해야 한다. OpenCode는 저장소를 읽고 파일을 수정하는 작업 계층이고, Ollama, vLLM, LM Studio 같은 서버는 실제 모델을 추론하는 계층이다. 팀이 공유하는 GPU 서버에는 오픈웨이트 모델을 올린다. 개발자 PC의 OpenCode가 사내 네트워크 주소로 요청을 보내는 구조가 기본형이다.

방 논의에서 소개된 흐름도 이 분업에 가깝다. PRD 작성과 검증에는 성능이 검증된 클라우드 모델을 쓰고 반복적인 구현은 사내 OpenCode에 맡긴다. OpenCode 자체가 모든 작업을 같은 모델로 처리해야 하는 것은 아니므로 가능한 조합이다.

실제로 연결하는 순서와 산출물

첫 단계는 모델 서버를 준비하는 일이다. Ollama를 쓰면 모델을 내려받아 로컬 API로 제공할 수 있고, vLLM을 쓰면 OpenAI 호환 서버를 열 수 있다. vLLM은 기본적으로 8000 포트에서 OpenAI 호환 서버를 열며, 로컬에서는 http://localhost:8000/v1로 쓸 수 있다. 원격 GPU 서버 주소로 바꿔 쓸 수도 있다고 설명한다.

그다음 저장소 루트에 opencode.json 또는 opencode.jsonc를 둔다. provider 아래에 OpenAI 호환 패키지와 모델 ID를 등록하고, options에 사내 서버의 baseURL을 설정하면 된다. 입력은 PRD, 기존 저장소, 테스트 명령어, 코딩 규칙이다. 산출물은 구현 계획, 수정된 파일, 실행 로그, 테스트 결과다.

OpenCode에는 계획을 검토하는 Plan 에이전트와 실제 변경을 수행하는 Build 에이전트가 기본으로 제공된다. Plan 모드에서 변경안을 검토한 뒤 Build 모드로 전환할 수 있다. 온프레미스 환경에서는 이 구분이 더 중요하다. 모델이 충분히 강하지 않다면 계획 단계에서 요구사항을 좁히고 구현 단계에는 작은 작업만 넘겨야 한다.

프로젝트를 처음 열었을 때 /init을 실행하면 AGENTS.md를 만들 수 있다. 이 파일에는 디렉터리 구조, 실행 방법, 코딩 규칙을 적어둘 수 있다. 팀은 이 파일을 저장소에 포함해 개발자마다 다른 프롬프트를 반복하지 않도록 할 수 있다.

무제한 사용보다 중요한 것은 작업 분할이다

온프레미스의 매력은 호출량에 따른 외부 과금과 사용량 제한에서 상대적으로 자유롭다는 점이다. 방 논의에서도 구현 작업을 많이 맡길 수 있다는 의견이 나왔다. 하지만 서버 비용이 사라지는 것은 아니다. GPU 메모리, 전력, 모델 관리, 모니터링, 동시 요청 처리가 모두 운영비로 남는다.

공유 인프라에서는 사용자가 몰리는 시간에 응답이 느려질 수 있다는 경험도 나왔다. 한 사람이 기다리는 구조라면 단순한 불편이다. 여러 개발자가 동시에 에이전트를 실행하면 대기열과 우선순위 문제가 된다. 그래서 모델 서버의 평균 응답 속도보다 피크 시간의 지연 시간과 동시 처리량을 측정해야 한다.

개인 개발자와 소규모 팀은 처음부터 거대한 모델을 공용 서버에 올릴 필요가 없다. PRD 요약, 파일 탐색, 테스트 초안, 반복적인 리팩터링처럼 실패 비용이 낮은 작업부터 맡기면 된다. 배포 설정, 인증 로직, 데이터베이스 마이그레이션처럼 실수의 영향이 큰 작업은 계획과 검증을 별도 모델 또는 사람의 승인 단계로 남겨두는 편이 안전하다.

성능보다 먼저 확인할 것은 도구 호출이다

일반적인 채팅에서 답변을 잘하는 모델과 OpenCode에서 파일을 읽고 수정하는 모델은 다를 수 있다. 에이전트가 작동하려면 모델이 파일 읽기, 검색, 셸 실행, 파일 쓰기 같은 도구를 올바른 형식으로 호출해야 한다. 모델이 도구 호출을 일반 텍스트나 XML처럼 출력하면 OpenCode는 명령으로 실행하지 못한다.

써본 사람들 사이에서도 작은 로컬 모델은 간단한 보일러플레이트에는 쓸 만하지만 긴 문맥과 여러 단계의 수정에서는 쉽게 흔들린다는 반응이 있다. 반대로 충분한 문맥 길이와 도구 호출을 지원하는 모델이라면 여러 파일을 수정할 수 있었다는 경험도 나온다. 모델 크기만 볼 것이 아니라 tool calling, context window, 양자화 방식, 서버의 요청 처리 방식을 함께 봐야 한다.

Ollama 쪽도 코딩 모델의 도구 호출 지원을 계속 개선하고 있다. Ollama는 2025년 10월 Qwen3-Coder-30B의 도구 호출이 더 빠르고 안정적으로 개선됐다고 밝혔다. 다만 특정 모델의 소개 문구만으로 사내 코드베이스에서의 성공률을 판단할 수는 없다. 같은 모델을 실제 저장소의 읽기·수정·테스트 과제로 평가해야 한다.

사내 도입의 기준은 모델이 아니라 검증 루프다

온프레미스 OpenCode를 도입할 때 가장 현실적인 흐름은 PRD 작성 → 구현 계획 → 작은 변경 → 테스트 실행 → 검토다. PRD에는 기능 목표와 제외 범위를 적고 OpenCode에는 한 번에 하나의 파일군이나 테스트 단위를 맡긴다. 모델이 생성한 코드는 자동 테스트와 정적 분석을 통과한 뒤 사람에게 전달한다.

검증 모델을 따로 두는 방식도 유효하다. 구현 모델은 사내 GPU에서 반복 작업을 처리한다. 더 강한 외부 모델이나 별도 검토 에이전트는 변경 이유와 테스트 결과를 확인한다. 모델 이름보다 중요한 것은 역할을 고정하는 일이다. 구현 모델이 스스로 만든 코드를 스스로 승인하게 두면 오류가 반복될 가능성이 커진다.

OpenCode는 조직 단위 설정도 지원한다. 공식 문서에 따르면 원격 설정, 프로젝트 설정, 관리자용 설정을 계층별로 적용할 수 있고 Linux에서는 /etc/opencode/에 관리 설정을 둘 수 있다. 사내 표준 모델, 허용 도구, MCP 서버, 권한 정책을 중앙에서 관리하려는 팀에 필요한 기반이다.

온프레미스 OpenCode는 클라우드 모델의 완전한 대체재라기보다 데이터가 밖으로 나가면 안 되거나 반복 호출이 많은 구현 업무를 분리하는 장치에 가깝다. 지금 확인해야 할 질문은 ‘무제한으로 쓸 수 있는가’가 아니다. 우리 저장소에서 모델이 도구를 정확히 호출하고 피크 시간에도 검증 가능한 결과를 내는가가 핵심이다.