# 🦙 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` 파일에 아래와 같이 구성합니다:

```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 확인
```bash
# 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) 이상으로 확장하는 것을 강력히 권장합니다.

```bash
# 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 기본 실행 (설정 파일 적용)
```bash
# 기본 설정된 Ollama 모델로 TUI 실행
opencode
```

### 4.2 CLI 플래그로 특정 모델 즉시 실행 (`-m`)
opencode 2.x 의 대화형 TUI(`opencode`)는 `-m`/`--model`·`--agent` 를 받지 않습니다(`Unrecognized flag`). TUI 의 모델은 설정 파일의 `"model"` 로 정하고, `-m` 은 비대화형 `run` 에서만 씁니다.
```bash
# 비대화형(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 에이전트로 띄울 때의 표준 명령어입니다. MAM 은 **opencode 2.x 만** 지원하며(Issue #60), pane 에서 `opencode --auto --standalone`(재개는 `--session <id>` 추가)으로 띄웁니다. `--standalone` 이라 서버가 TUI 의 자식으로 떠서 세션을 닫으면 함께 끝나고, 사용자별 백그라운드 서비스는 쓰지도 띄우지도 않습니다.

```bash
# 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"
```