OpenCode와 Ollama가 작동하지 않을 때는 모델을 바꾸기 전에 서버 엔드포인트와 정확한 모델 ID부터 확인하세요. 두 확인을 모두 통과했다면, 작은 파일 편집을 테스트해서 도구 호출 문제인지 연결 문제인지 구분하세요. 채팅 요청에 응답할 수 있는 모델은 코딩 에이전트 워크플로우의 첫 단계만 통과한 것입니다.
이 가이드는 Ollama와 OpenCode가 이미 설치되어 있다는 전제하에 작성되었습니다. 설치 및 프로바이더 설정은 Ollama와 OpenCode 설정 가이드를 참고하세요. 여기서 설명하는 절차는 현재 작동 중인 설정을 계속 바꾸지 않으면서 문제의 원인을 좁혀 가는 방식입니다.
어떤 요청이 실패하는지 파악하기
OpenCode 장애는 추론 전, 생성 중, 도구 실행 시 세 단계에서 발생할 수 있습니다. 각 단계를 따로 확인하세요. 연결 거부와 모델이 JSON처럼 보이는 문단을 반환하는 경우와 전혀 다른 문제입니다. 설정을 변경하기 전에 엔드포인트, 선택한 모델, 오류 내용을 기록해 두면 변경이 효과가 있었는지 판단할 수 있습니다.
| 관찰 결과 | 다음 확인 사항 | 이 결과로 알 수 있는 것 |
|---|---|---|
| 연결 거부 | 구성된 호스트와 포트로 /api/version 요청 | 해당 Ollama 엔드포인트에 도달 가능한지 여부 |
| 모델을 찾을 수 없음 | /v1/models을 읽고 정확한 ID 비교 | 요청한 모델이 해당 서버에 존재하는지 여부 |
| 채팅은 되는데 파일이 바뀌지 않음 | 도구 호출과 권한 결과 검사 | OpenCode가 작업을 시도하고 완료했는지 여부 |
| 작은 편집은 되는데 큰 작업은 실패 | 할당된 컨텍스트와 런타임 로그 검사 | 더 큰 작업에서 측정 가능한 한계에 부딪히는지 여부 |
| 로컬은 되는데 클라우드는 중단됨 | 두 경로를 각각 테스트 | 장애가 클라우드 경로에만 해당하는지 여부 |
장애를 재현하기 전에 버전을 기록하세요:
opencode --version
ollama --version
이 글의 로컬 점검에는 Apple M3 Ultra(통합 메모리 96 GB)에서 OpenCode 1.19.4와 Ollama 0.32.9를 사용했습니다. 이 하드웨어라면 선택한 31B 모델을 실행할 수 있지만, 더 작은 노트북에 대한 메모리 권장 사항은 아닙니다. 다른 하드웨어에서의 모델 선택은 Ollama 코딩 모델 가이드를 참고하세요.
모델을 바꾸기 전에 엔드포인트 확인
OpenCode가 사용하는 것과 동일한 호스트와 포트에 요청하세요. 127.0.0.1:11434의 로컬 서버와 127.0.0.1:11435의 서버는 서로 다른 엔드포인트입니다. 요청이 실패하면 서버나 주소를 먼저 복구하세요. 모델을 바꿔도 거부된 네트워크 연결은 고칠 수 없습니다.
curl --fail-with-body --max-time 5 \
http://127.0.0.1:11434/api/version
curl --fail-with-body --max-time 5 \
http://127.0.0.1:11434/v1/models
버전 응답이 오면 Ollama가 응답하고 있다는 뜻입니다. 모델 목록 응답은 해당 서버가 노출하는 모델 ID를 보여줍니다. 빈 목록은 서버에는 도달하지만 나열된 모델이 없다는 의미이며, 연결 오류와는 다릅니다.
Ollama가 중지되어 있다면 애플리케이션을 시작하거나 터미널에서 서버를 실행하세요:
ollama serve
포트가 이미 사용 중이라면 다른 인스턴스를 띄우지 말고 어떤 서버가 실행 중인지 먼저 확인하세요. 원격 Ollama 설치에는 해당 원격 주소가 필요하며, 127.0.0.1은 항상 클라이언트를 실행하는 머신 자체를 가리킵니다.
Ollama의 OpenCode 통합 문서는 /v1로 끝나는 OpenAI 호환 base URL을 사용합니다. OpenCode 프로바이더 설정에서 이 접미사를 그대로 유지하세요. /api/version 같은 네이티브 진단 경로는 이 범위 밖에 있습니다.
구성된 모델을 서버의 정확한 ID와 일치시키기
서버가 반환하는 모델 ID를 태그 포함 그대로 사용하세요. 한 Ollama 서버에서 다운로드한 모델은 같은 모델이 설치되어 있지 않은 한 다른 서버에서 사용할 수 없습니다. 요청을 다시 보내기 전에 선택한 프로바이더, base URL, 모델 선언을 함께 확인하세요.
OpenCode 1.19.4 확인에 사용한 프로바이더 구성은 다음과 같습니다:
{
"provider": {
"ollama": {
"npm": "@ai-sdk/openai-compatible",
"options": {
"baseURL": "http://127.0.0.1:11434/v1"
},
"models": {
"gemma4:31b": {
"name": "Gemma 4 31B",
"limit": {
"context": 65536,
"output": 2048
}
}
}
}
}
}
gemma4:31b을 서버에 실제로 나열된 ID로 바꾸세요. 이 예시는 해당 모델을 다운로드하지 않습니다. OpenCode의 전체 선택자는 프로바이더 이름과 모델 ID를 결합한 형태입니다:
opencode run -m ollama/gemma4:31b "Reply with one short sentence."
일부러 존재하지 않는 모델을 Ollama의 호환 엔드포인트를 통해 요청해 보았고, not_found_error와 함께 HTTP 404를 받았습니다. 이 결과는 모델 선택 오류임을 보여 줍니다. 메모리 부족이나 도구 파서 오류를 나타내는 것은 아닙니다.
설정은 여러 위치에서 가져올 수 있습니다. OpenCode 설정 문서는 설정이 병합되는 방식을 설명합니다. 값이 무시되는 것 같을 때는 로컬에서 확인된 최종 설정을 검사하세요:
opencode debug config
확인된 최종 설정에는 자격 증명이 포함될 수 있습니다. 진단 보고서를 공유하기 전에 관련 프로바이더 설정만 추출하고, 키나 관련 없는 계정 정보는 제거하세요.
일회용 코딩 픽스처로 작업 확인
변경된 파일을 직접 확인하고 테스트도 직접 실행하세요. OpenCode에 알려진 버그가 하나 있는 작은 파일을 주고, 파일 수정을 요청한 뒤 독립적인 검사를 실행합니다. 이렇게 하면 파일 접근, 편집, 실행을 모두 테스트하면서 진단을 검사할 수 있을 정도로 작게 유지할 수 있습니다.
새 디렉터리를 만들고 이동하세요:
mkdir opencode-ollama-check
cd opencode-ollama-check
cat > add.mjs <<'JS'
export function add(a, b) {
return a - b;
}
JS
cat > check.mjs <<'JS'
import { add } from './add.mjs';
if (add(2, 3) !== 5) throw new Error('Expected add(2, 3) to return 5');
console.log('PASS');
JS
node check.mjs
첫 번째 검사는 실패해야 정상입니다. 테스트한 프로바이더 설정을 이 일회용 디렉터리에 복사한 뒤 실행하세요:
opencode run -m ollama/gemma4:31b \
"Read add.mjs. Fix add so it adds its arguments. Run node check.mjs."
node check.mjs
add.mjs을 직접 확인하세요. 파일이 여전히 뺄셈을 하고 있거나 독립적 검사가 실패한다면, 모델이 성공 메시지를 출력했더라도 충분하지 않습니다. 권한 프롬프트가 보이도록 유지해서 거부된 편집과 누락된 도구 호출을 구분할 수 있게 하세요. 확인 과정에서 macOS는 픽스처를 /private/tmp 아래에서 해결했지만, 도구는 /tmp 별칭을 요청했습니다. OpenCode는 별칭 경로를 외부 경로로 간주하고 비대화형 실행에서 거부했습니다. 확인된 실제 디렉터리와 상대 파일 경로를 사용하니 좁은 범위의 권한으로 픽스처를 실행할 수 있었습니다.
더 깊이 검사하려면 OpenCode CLI의 JSON 출력을 활용할 수 있습니다:
opencode run --format json -m ollama/gemma4:31b \
"Read add.mjs and explain the implementation."
실행된 도구와 그 결과를 찾으세요. 함수 이름이나 JSON 객체가 포함된 텍스트만으로는 OpenCode가 실제로 무언가를 실행했는지 증명되지 않습니다. 엔드포인트와 픽스처 권한을 수정한 뒤, 한 번의 수정 실행에서 픽스처를 읽고 뺄셈을 덧셈으로 바꿔 독립적 Node 검사를 통과했습니다. 두 번째 실행은 의도적으로 비워 둔 모델 ID를 교체한 후 동일한 검사를 통과했습니다. 별도의 직접 API 프로브에서는 Gemma 4 31B가 65,536 컨텍스트에서 구조화된 read_file 호출을 반환했습니다. 이 단일 결과는 프로브의 응답 형식을 검증하는 것이지, 코딩 작업 전반의 신뢰성을 검증하는 것은 아닙니다.
Ollama가 실제로 할당한 컨텍스트 확인
OpenCode에 표시된 모델 한도와 Ollama의 런타임 할당이 일치해야 합니다. 클라이언트 설정에서 숫자를 높인다고 서버가 더 많은 컨텍스트를 할당하는 것은 아닙니다. 요청 중에 실행 중인 모델을 검사한 다음, 실제 컨텍스트를 작업의 프롬프트 및 도구 이력과 비교하세요.
Ollama 컨텍스트 문서는 코딩 도구와 에이전트에 최소 64,000 토큰을 권장합니다. 할당이 커지면 메모리 소비도 늘어난다는 점도 함께 설명합니다. 수동으로 시작한 서버에서는 명시적 할당을 설정할 수 있습니다:
OLLAMA_CONTEXT_LENGTH=65536 ollama serve
이 변수는 Ollama를 실행하는 프로세스에 설정하세요. OpenCode를 실행하는 터미널에서만 export하면 이미 실행 중인 Ollama 애플리케이션에는 반영되지 않습니다. 애플리케이션이 서버를 관리하는 경우 애플리케이션 자체의 컨텍스트 설정을 사용하세요.
모델이 로드되어 있는 동안 검사하세요:
ollama ps
CONTEXT 및 PROCESSOR 열을 확인하세요. Ollama가 사용자 정의 호스트나 포트를 사용 중이라면 CLI도 해당 서버를 가리키도록 설정하세요. 메모리 부족, CPU 오프로딩, 잘림, 도구 형식 실패는 각각 별도의 증거가 필요하며, 응답이 느리다는 것만으로는 어떤 문제가 발생했는지 특정할 수 없습니다.
하드웨어가 필요한 컨텍스트를 감당할 수 없다면, 도구를 지원하는 더 작은 모델을 선택하고 동일한 픽스처를 반복하세요. 서로 다른 작업으로 두 모델을 비교한 뒤 그 차이를 모델 품질 탓으로 돌리지 마세요.
유용한 장애 보고서 작성
유용한 보고서는 다른 개발자가 동일한 요청을 재현할 수 있게 해 줍니다. 버전, 민감 정보를 제거한 프로바이더 설정, 정확한 모델 태그, 할당된 컨텍스트, 여전히 실패하는 가장 작은 픽스처를 포함하세요. 직접 요청이 성공하는지, OpenCode가 모델 서버에 도달하는지도 기록하세요. 이런 세부 정보가 메인테이너가 장애 원인을 찾는 데 도움이 됩니다.
OpenCode 문제 해결 가이드는 로그 위치를 찾는 방법을 설명합니다. 테스트한 버전에서는 아래 명령으로 구성된 데이터 및 로그 경로를 확인할 수 있습니다:
opencode debug paths
로컬 결과와 클라우드 결과는 분리해서 관리하세요. 로컬 코딩 테스트로는 Ollama Cloud 인증이나 가용성을 검증할 수 없고, 클라우드 장애가 로컬 도구 사용의 성능 저하를 증명하지도 않습니다. 마찬가지로, 동일한 증상을 다루는 오래된 이슈가 제안한 수정 사항이 현재 설치된 버전에 적용된다는 보장은 없습니다.
픽스처는 성공하는데 리포지토리 작업이 실패한다면, 작동하는 픽스처를 유지하면서 점진적으로 복잡도를 높이세요. 파일 추가, 더 큰 입력, 더 긴 도구 시퀀스 등을 시도해 보세요. 장애를 재현하는 첫 번째 변경 지점을 찾는 것이 비교 없이 양쪽 애플리케이션을 재설치하는 것보다 유용합니다.
로컬 진단을 마친 후 다른 프로바이더를 설정하려면 OpenCode 커스텀 프로바이더 가이드에서 Haimaker 설정 방법을 확인할 수 있습니다. 비공개 로컬 테스트는 로컬에 유지하세요. 프로바이더 전환은 워크로드가 허용할 때 선택적으로 진행하면 됩니다.
자주 묻는 질문
Ollama 채팅이 성공하면 OpenCode 도구도 작동하나요?
아닙니다. 채팅 응답은 모델이 텍스트를 생성할 수 있다는 것만 증명합니다. OpenCode에는 구조화된 도구 호출, 실행 권한, 작업에 충분한 컨텍스트도 필요합니다. 실제 파일 편집과 테스트 결과를 확인하세요.
OpenCode의 컨텍스트 한도를 높이면 Ollama 메모리가 더 할당되나요?
OpenCode에 표시된 컨텍스트 한도는 Ollama가 해당 컨텍스트를 할당했음을 증명하지 않습니다. Ollama 서버를 구성하고 ollama ps로 실행 중인 모델을 검사하세요. 컨텍스트가 커지면 메모리 요구량도 증가합니다.
Ollama 모델이 OpenCode에서 사라지면 모든 것을 재설치해야 하나요?
먼저 Ollama가 반환하는 모델 ID와 OpenCode 설정에 선언된 모델을 비교하세요. 재설치 전에 엔드포인트와 선택된 프로바이더부터 확인하세요.