131 lines
4.2 KiB
Markdown
131 lines
4.2 KiB
Markdown
# 🦙 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`)
|
|
```bash
|
|
# 대화형 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 에이전트로 띄울 때의 표준 명령어:
|
|
|
|
```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"
|
|
```
|