🦙 OpenCode (`anomalyco/opencode`) — Ollama 연동 및 기본 모델 설정 가이드

본 문서는 OpenCode CLI/TUI 환경에서 로컬 Ollama 프로바이더와 모델을 기본값(Default)으로 연결하고 최적화하여 사용하는 방법을 정리한 가이드입니다.

1. 설정 파일 위치 (`opencode.jsonc` vs `opencode.json`)

OpenCode는 JSONC (JSON with Comments) 형식을 공식 지원하므로 주석(//, /* */) 작성이 가능한 opencode.jsonc를 기본 설정 파일로 사용합니다. (.json과 .jsonc 둘 다 동일하게 인식됩니다.)

전역 설정 경로 (추천):
- ~/.config/opencode/opencode.jsonc (또는 ~/.config/opencode/opencode.json)
프로젝트별 로컬 설정 경로:
- <project-root>/opencode.json (특정 프로젝트 루트 디렉터리에 위치)

2. 권장 설정 내용 (`opencode.jsonc`)

~/.config/opencode/opencode.jsonc 파일에 아래와 같이 구성합니다:

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

  // 1. 기본 실행 모델 (형식: "provider_id/model_id")
  "model": "ollama/qwen2.5-coder:32b",

  // 2. Ollama 프로바이더 상세 엔드포인트 및 모델 정의
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": {
        "baseURL": "http://127.0.0.1:11434/v1"
      },
      "models": {
        "qwen2.5-coder:32b": {
          "name": "Qwen 2.5 Coder 32B"
        },
        "glm-5.3:cloud": {
          "name": "GLM 5.3 Cloud"
        }
      }
    }
  }
}

Tip

qwen2.5-coder:32b 대신 본인의 머신에 설치된 Ollama 모델 태그명(예: qwen2.5-coder:14b, llama3.1:8b, deepseek-r1:14b 등)을 기재하시면 됩니다.

3. Ollama 사용 시 필수 사전 준비 (Critical)

3.1 Ollama 서비스 구동 및 API 확인

# Ollama 모델 목록 확인
ollama list

# OpenAI 호환 v1 엔드포인트 응답 확인
curl http://127.0.0.1:11434/v1/models

3.2 컨텍스트 윈도우(`num_ctx`) 확장

Ollama의 기본 컨텍스트 크기는 4,096 토큰으로 매우 작아서, 에이전트가 파일 트리나 긴 소스 코드를 읽을 때 컨텍스트 오버플로우가 발생할 수 있습니다. Modelfile을 작성하여 32K(32,768) 이상으로 확장하는 것을 강력히 권장합니다.

# 1) Modelfile 생성
cat << 'EOF' > Modelfile
FROM qwen2.5-coder:32b
PARAMETER num_ctx 32768
EOF

# 2) 확장된 커스텀 모델 빌드
ollama create qwen2.5-coder-32k -f Modelfile

빌드 후 opencode.jsonc의 "model"을 "ollama/qwen2.5-coder-32k"로 지정합니다.

3.3 Tool Calling(함수 호출) 지원 모델 선택

OpenCode는 파일 읽기/수정, 셸 실행 등을 모델의 Tool Calling 기능으로 처리합니다.

추천 모델: qwen2.5-coder (7b/14b/32b), llama3.1 (8b/70b), mistral-nemo

4. 실행 및 런타임 제어

4.1 기본 실행 (설정 파일 적용)

# 기본 설정된 Ollama 모델로 TUI 실행
opencode

4.2 CLI 플래그로 특정 모델 즉시 실행 (`-m`)

# 대화형 TUI 실행
opencode -m "ollama/qwen2.5-coder:32b"

# 비대화형(Headless) 무인 단발 태스크 실행
opencode run -m "ollama/qwen2.5-coder:32b" "tests/ 단위 테스트를 실행하고 실패하는 테스트를 고쳐줘"

4.3 TUI 실행 중 대화식 모델 전환

OpenCode 대화창에서 Tab 키를 누르거나 프롬프트에 /models를 입력하여 등록된 모델 목록 중 원하는 모델을 즉시 선택할 수 있습니다.

5. Multi-Agent Mux (MAM) 연동 예시

MAM 환경에서 OpenCode를 reviewer/creator 에이전트로 띄울 때의 표준 명령어:

# 1. 세션 생성 및 온보딩
bash .agents/skills/multi-agent-mux-create/scripts/create_session.sh \
  --workspace "$(pwd)" \
  --agent "opencode" \
  --role "reviewer" \
  --session "reviewer-opencode-01" \
  --herdr-session "multi-agent-mux" \
  --herdr-workspace "mam-agent" \
  --onboard

# 2. 세션 대화 복원 (Resume)
bash .agents/skills/multi-agent-mux-resume/scripts/resume_session.sh \
  --workspace "$(pwd)" \
  --agent "opencode" \
  --session "reviewer-opencode-01" \
  --herdr-session "multi-agent-mux"

4.2 KiB Raw Blame History

🦙 OpenCode (anomalyco/opencode) — Ollama 연동 및 기본 모델 설정 가이드

1. 설정 파일 위치 (opencode.jsonc vs opencode.json)

2. 권장 설정 내용 (opencode.jsonc)