OpenCode × Ollama로 로컬 완결형 셀프 호스팅 코딩 에이전트 구축하기

터미널에서 동작하는 AI 코딩 에이전트가 급격히 늘어났습니다. 그중에서도 OpenCode는 GitHub 스타 17만 개 초과(2026년 6월 시점)를 기록하며 가장 많은 스타를 모은 OSS 코딩 에이전트입니다. Claude Code와 유사한 사용감을 특정 벤더에 얽매이지 않고 자신의 인프라 위에서 실행할 수 있다는 점이 큰 특징입니다.

이 기사에서는 OpenCode를 도입하고, Ollama를 통해 로컬 LLM에 연결하여 "코드가 클라우드로 나가지 않는" 셀프 호스팅형 코딩 에이전트 환경을 구축하는 절차를 실제 설정 파일과 함께 해설합니다. 직접 재현할 수 있는 핸즈온을 목표로 합니다.

• OpenCode의 위치 (누가 만들었으며, 무엇을 할 수 있는가)

• 설치부터 첫 실행까지

• opencode.json으로 Ollama의 로컬 모델에 연결하는 설정 작성법 - 글로벌 설정과 프로젝트 설정의 구분

• AGENTS.md의 역할

• 로컬 모델 사용 시 발생하기 쉬운 "도구 호출(Tool Calling)이 작동하지 않는" 문제의 회피책

• Claude Code 등 클라우드형 에이전트를 사용 중이지만, 코드를 외부로 유출하고 싶지 않은 분

• 로컬 LLM (Ollama)으로 완결되는 개발 환경에 관심이 있는 엔지니어

• 벤더 락인(Vendor Lock-in)을 피하고 여러 프로바이더를 전환하고 싶은 분

• macOS / Linux / Windows 중 하나 (터미널 사용 가능할 것)

• 로컬 모델을 사용하는 경우 Ollama가 설치되어 있을 것

버전이나 세부 사양은 업데이트가 빠른 영역입니다. 최신 절차는 반드시 공식 문서를 확인해 주세요. 본 기사는 2026년 6월 시점의 공식 문서를 바탕으로 하고 있습니다.

• OpenCode는 **Anomaly (SST에서 파생된 팀)**가 개발하는 MIT 라이선스의 OSS 터미널 에이전트입니다.
• curl -fsSL https://opencode.ai/install | bash 한 줄로 도입할 수 있습니다.
• Models.dev 카탈로그를 통해 75개 이상의 프로바이더를 지원하며, Ollama / LM Studio / llama.cpp 등 로컬 모델도 사용할 수 있습니다.
• 로컬 모델은 opencode.json의 provider에 @ai-sdk/openai-compatible와 baseURL: http://localhost:11434/v1을 작성하는 것만으로 연결됩니다.
• 로컬 모델에서 도구 호출이 불안정할 때는 Ollama 측의 num_ctx를 16k~32k로 높입니다.

OpenCode는 터미널에 상주하는 TUI (Text User Interface)형 코딩 에이전트입니다. 파일 편집, 명령 실행, 코드베이스 탐색을 에이전트에게 맡길 수 있다는 점은 Claude Code나 Codex CLI와 같지만, 다음과 같은 특징이 있습니다.

• 오픈 소스 (MIT 라이선스): 리포지토리는 anomalyco/opencode (구 sst/opencode)입니다. 포크, 자체 빌드, 개정이 자유롭습니다.
• 프로바이더 비의존성: Models.dev 카탈로그를 통해 75개 이상의 LLM 프로바이더를 지원합니다. OpenAI 호환 API라면 로컬 모델도 추가할 수 있습니다.
• LSP 연동: Language Server Protocol에 대응하여, 에이전트가 타입 정보나 진단 정보를 참조할 수 있습니다.
• 에디터 비의존성: VS Code / Cursor / Zed 등 터미널을 가진 임의의 환경의 통합 터미널에서 동작합니다.

개발원은 인프라 계열 OSS로 알려진 SST에서 파생된 Anomaly (anomalyco)입니다.

"OpenCode를 사용하면 Claude 모델을 자유롭게 쓸 수 있다"는 의미는 아닙니다. 이용 가능한 모델은 계약 중인 프로바이더의 API 키에 달려 있습니다. 로컬 완결을 목표로 한다면, 후술할 Ollama 연동이 현실적인 선택지가 됩니다.

클라우드형 코딩 에이전트는 강력하지만, 업무 코드를 다루는 상황에서는 다음과 같은 우려가 뒤따릅니다.

우려 사항	로컬 self-host를 통한 해결
소스 코드가 외부 API로 전송됨	모델 추론을 로컬의 Ollama에서 완결하면 코드가 외부로 나가지 않음
...

OpenCode는 "클라우드 프론티어 모델 (Frontier Model)"과 "로컬 모델"을 설정 파일로 자유롭게 전환할 수 있기 때문에, 기밀성이 높은 리포지토리(Repository)만 로컬 모델을 사용하고, 그 외에는 클라우드를 사용하는 식의 구분 활용도 가능합니다.

가장 빠른 방법은 설치 스크립트입니다.

curl -fsSL https://opencode.ai/install | bash

이 외에도 선호하는 패키지 매니저(Package Manager)로 도입할 수 있습니다.

# npm (Bun / pnpm / Yarn 도 가능)
npm install -g opencode-ai
# Homebrew (macOS / Linux)
...

Windows에서는 Chocolatey / Scoop / Mise, Arch Linux에서는 Pacman도 이용할 수 있습니다.

설치 후, 프로젝트 디렉토리에서 실행합니다.

cd your-project
opencode

TUI가 실행되면, /connect를 실행하여 프로바이더(Provider)를 선택하고 API 키를 붙여넣으면 클라우드 모델을 즉시 사용할 수 있습니다. 여기서부터가 본론인 로컬 연결입니다.

먼저 Ollama 측에서 모델을 실행해 둡니다.

# 예: 코드 생성에 적합한 모델을 가져와서 실행
ollama pull qwen2.5-coder:7b
ollama serve # 이미 상주 중인 경우 불필요

Ollama는 OpenAI 호환 엔드포인트(http://localhost:11434/v1)를 제공합니다. OpenCode 측에서는 이 엔드포인트를 "OpenAI 호환 프로바이더 (OpenAI Compatible Provider)"로 등록하기만 하면 됩니다.

프로젝트 루트에 opencode.json을 생성합니다.

{
"$schema": "https://opencode.ai/config.json",
"provider": {
...

설정의 핵심 요점은 다음 세 가지입니다.

• npm: 로컬 연결에는 OpenAI 호환 어댑터 @ai-sdk/openai-compatible를 지정한다.
• options.baseURL: Ollama의 OpenAI 호환 엔드포인트. 끝에 /v1을 잊지 말 것.
• models: 사용할 모델 ID (ollama pull한 태그)와 표시 이름을 등록한다.

model 키는 프로바이더 ID/모델 ID 형식이며, 여기서는 ollama/qwen2.5-coder:7b를 기본 모델로 설정했습니다. 이 상태에서 opencode를 실행하면, 추론은 모두 로컬의 Ollama에서 수행되며 코드가 외부로 전송되는 일은 없습니다.

로컬 모델에서는 "파일 편집", "명령 실행" 등의 도구 호출 (Function Calling)이 불안정해질 수 있습니다. OpenCode의 공식 문서에서는 도구 호출이 제대로 작동하지 않을 경우, Ollama 측의 컨텍스트 길이(Context Length)인 num_ctx를 16k~32k로 높일 것을 권장하고 있습니다.

num_ctx는 Ollama의 Modelfile이나 요청 시 옵션으로 지정합니다.

# Modelfile로 컨텍스트 길이를 높이는 예시
cat > Modelfile <<'EOF'
FROM qwen2.5-coder:7b
...

생성한 모델을 opencode.json의 models에 다시 등록하면 도구 호출의 안정성이 개선됩니다.

OpenCode의 설정 파일은 두 곳에 둘 수 있습니다.

종류	경로	용도
글로벌 (Global)	~/.config/opencode/opencode.json	모든 프로젝트 공통 기본 프로바이더 및 모델
프로젝트 (Project)	<project>/opencode.json	해당 리포지토리 전용 덮어쓰기 설정

두 가지 모두 JSON / JSONC(주석 가능)로 작성할 수 있습니다. 기밀 리포지토리(Repository)에만 ollama/... 를 기본값으로 설정한 프로젝트 설정을 두고, 그 외에는 글로벌(Global) 설정에서 클라우드 모델을 사용하는 방식의 운영이 자연스럽습니다.

small_model을 병용하면, 코드 완성(Completion)이나 제목 생성과 같은 가벼운 태스크를 저렴한 모델(또는 로컬 모델)에 할당할 수 있습니다.

{
"$schema": "https://opencode.ai/config.json",
"model": "ollama/qwen2.5-coder:7b",
...
}

Claude Code의 CLAUDE.md에 해당하는 것이 AGENTS.md입니다. 프로젝트 루트(Root)에 두면, OpenCode가 에이전트에 대한 지시 사항으로 읽어들입니다.

# AGENTS.md
## 이 리포지토리의 방침
- 패키지 매니저(Package Manager)는 pnpm을 사용한다
...

AGENTS.md는 OpenCode 이외의 에이전트 도구에서도 채택이 진행되고 있는 공통 포맷입니다. 도구를 교체하더라도 지시 사항을 재사용하기 쉽다는 것이 장점입니다.

실제로 구동할 때 빠지기 쉬운 주의 사항을 정리합니다.

• Ollama를 OpenAI 호환 방식으로 사용할 때: baseURL의 /v1 누락 주의. http://localhost:11434/v1이 필수입니다. 순수하게 http://localhost:11434만 입력하면 에러가 발생합니다.

• 도구 호출(Tool Calling)이 작동하지 않음: 앞서 언급한 num_ctx 상향 조정과 더불어, 도구 호출을 지원하는 모델(Qwen2.5 Coder 등)을 선택해야 합니다. 너무 작은 모델은 함수 호출(Function Calling)에 취약합니다.

• 모델이 목록에 나타나지 않음: opencode.json의 models에 명시적으로 등록하지 않으면 선택지에 나타나지 않습니다. ollama pull로 받은 태그 이름과 일치시켜야 합니다.

• 속도 저하: 로컬 추론(Inference)은 GPU 유무에 따라 체감 성능이 크게 달라집니다. 무거운 태스크는 클라우드 모델, 기밀 태스크는 로컬 모델로 구분하여 사용하는 것이 현실적입니다.

• OpenCode는 MIT 라이선스의 OSS 터미널 에이전트로, 프로바이더(Provider) 독립성 및 로컬 모델 대응이 강점입니다.

• curl -fsSL https://opencode.ai/install | bash로 도입하고, opencode.json에 OpenAI 호환 프로바이더로서 Ollama를 등록하면 로컬 완결형 환경을 구축할 수 있습니다.

• 설정은 글로벌과 프로젝트 단위로 덮어쓰기가 가능하여, 기밀 리포지토리만 로컬 모델로 운영하는 것이 가능합니다.

• 로컬 모델의 도구 호출이 불안정할 때는 num_ctx를 16k~32k로 높이십시오.

"코드를 외부로 유출하지 않고 AI 코딩 에이전트를 사용하고 싶다"라는 요구사항은 그동안 진입 장벽이 높았습니다. OpenCode와 Ollama의 조합이라면 설정 파일 하나로 그것이 현실이 됩니다. 우선 작은 리포지토리에서 로컬 모델을 테스트해 보고, 용도에 따라 클라우드 모델과 구분하여 사용해 보시기 바랍니다.

• OpenCode 공식 문서 — 전체 구조 및 도입 절차
• Config | OpenCode Docs — opencode.json의 구조와 키
• Providers | OpenCode Docs — Ollama 등 로컬 모델 설정
• anomalyco/opencode | GitHub — 리포지토리 (MIT 라이선스)
• Models.dev — 대응 프로바이더 및 모델 카탈로그