Prime Agent Ollama 2026 연결 장애 해결

모델은 보이지만 파일 수정과 테스트 실행 단계에서 멈춥니다.

가장 빠른 해결법은 재설치가 아니라 Ollama 서비스, 접속 주소, models.json, API 호환 설정, 모델 능력의 다섯 층을 순서대로 분리하는 것입니다.

마지막 업데이트: 2026년 8월 11일. Prime Agent 최신 저장소와 모델 설정 문서, Ollama 공식 API 및 장애 대응 문서를 기준으로 내용을 다시 확인했습니다.

이 글은 이미 Prime Agent와 Ollama를 설정했지만 모델이 나타나지 않는 개인 개발자에게 적합합니다. 로컬 모델은 연결되지만 요청 오류, 도구 동작 실패, 출력 중단을 겪는 AI 엔지니어도 대상입니다. 원격 환경에서 Prime Agent를 계속 실행하려는 플랫폼 팀은 마지막 환경 판단 부분부터 확인하면 됩니다.

먼저 나누는 다섯 가지 고장 층

Prime Agent의 모델 목록에 Ollama가 나타나지 않는 문제와, 모델은 보이지만 코딩 작업이 실패하는 문제는 같은 장애가 아닙니다. 다음 순서로 나누면 불필요한 재설치를 피할 수 있습니다.

서비스 층: Ollama가 실행 중인지 확인합니다.
주소 층: Prime Agent가 접근하는 baseUrl이 실제 Ollama 위치를 가리키는지 확인합니다.
설정 층: 올바른 위치의 models.json을 읽고 있는지 확인합니다.
호환성 층: developer 역할이나 reasoning_effort 같은 요청 필드를 서버가 받는지 확인합니다.
능력과 자원 층: 모델이 파일 수정, 명령 실행, 장기 작업을 안정적으로 수행하는지 확인합니다.

Prime Agent는 사용자 권한으로 생성된 코드와 명령을 실행하므로, 연결이 된 뒤에는 공식 저장소의 보안 안내처럼 신뢰할 수 있는 작업 폴더와 별도 검토 절차를 사용하는 편이 안전합니다.

서비스와 모델 목록 확인

Prime Agent에서 Ollama 모델이 보이지 않는 이유는 무엇인가요?

먼저 Prime Agent를 의심하지 말고 Ollama를 독립적으로 호출합니다. 로컬 셸에서 다음 명령을 실행합니다.

ollama list
curl http://localhost:11434/api/version
curl http://localhost:11434/api/tags

첫 번째 명령에 목표 모델이 없으면 모델이 설치되지 않았거나 이름이 다릅니다. api/tags가 모델 목록을 반환하면 Ollama 서비스와 모델 저장소는 일단 정상으로 볼 수 있습니다. 응답이 없거나 연결 거부가 나오면 Prime Agent 설정을 고치기 전에 Ollama를 실행하고 포트와 로그를 확인해야 합니다.

Ollama는 OpenAI 호환 경로에서 모델 목록을 /v1/models로 제공하며, 채팅 요청에는 /v1/chat/completions를 사용할 수 있습니다. 실제 지원 범위는 버전에 따라 달라질 수 있으므로 Ollama 공식 호환 API 문서를 기준으로 확인해야 합니다.

curl http://localhost:11434/v1/models

판단은 다음처럼 나누면 됩니다.

증상	먼저 확인할 것	확인 결과	다음 조치
Ollama 자체 모델 목록이 비어 있음	`ollama list`, `/api/tags`	모델 이름 없음	목표 모델을 설치하거나 실제 이름으로 수정
Ollama 목록은 정상, Prime Agent에 없음	`models.json` 위치와 문법	파일 미로드 또는 잘못된 배열	설정 경로와 JSON 구조 수정
Prime Agent에 모델은 보임, 호출 실패	`baseUrl`, API 종류, 로그	주소 또는 경로 오류	`/v1` 포함 여부와 접근 위치 수정
짧은 대화는 성공, 도구 요청은 실패	호환 설정과 모델 기능	역할·추론·도구 필드 거부	한 필드씩 비활성화해 재검사
작업 중단 또는 긴 지연	메모리, 모델 로딩, 문맥 증가	자원 또는 능력 한계	모델 교체, 작업 축소, 지속 환경 검토

models.json 읽기 경로 점검

Prime Agent의 공식 모델 설정은 사용자 홈 아래의 ~/.prime/agent/models.json을 사용합니다. 이 파일은 모델 공급자, 주소, API 종류, 인증 값, 모델 ID를 함께 정의하는 역할을 합니다. 현재 설정 방식은 기반이 되는 Pi 모델 문서와 Prime Agent의 공급자 안내에서 확인할 수 있습니다. 사용자 지정 모델 설정 예시를 먼저 대조하십시오.

최소 구조는 다음과 같습니다.

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        {
          "id": "qwen2.5-coder:7b"
        }
      ]
    }
  }
}

여기서 중요한 점은 세 가지입니다.

id는 화면에 표시할 별칭이 아니라 Ollama에 실제 전달할 모델 ID입니다.
baseUrl은 일반 Ollama API 주소가 아니라 OpenAI 호환 경로를 사용할 때의 주소입니다.
로컬 Ollama는 실제 키를 요구하지 않더라도 클라이언트가 인증값을 요구할 수 있으므로 문서 예시처럼 자리표시자 값을 둘 수 있습니다.

파일을 수정한 뒤 Prime Agent를 무조건 다시 설치할 필요는 없습니다. 모델 선택 화면을 다시 열어 설정이 반영되는지 확인합니다. 문서상 사용자 지정 모델 파일은 모델 선택 화면을 열 때 다시 읽을 수 있습니다. 그래도 목록이 갱신되지 않으면 다음을 실행해 현재 세션과 백그라운드 서비스 상태를 확인합니다.

prime-agent status
prime-agent doctor

JSON 오류는 다음 명령으로 빠르게 찾을 수 있습니다.

python -m json.tool ~/.prime/agent/models.json

파일이 정상이라도 모델 ID가 qwen2.5-coder:7b가 아닌 qwen2.5-coder처럼 다르면 모델 선택은 성공해도 호출 단계에서 실패할 수 있습니다.

접속 주소와 원격 경계 확인

Prime Agent의 baseUrl은 어떻게 입력해야 하나요?

Prime Agent와 Ollama가 같은 컴퓨터에서 실행되면 일반적으로 다음 형식을 사용합니다.

http://localhost:11434/v1

Ollama의 기본 API 포트와 OpenAI 호환 경로를 함께 적는 방식입니다. 단, Prime Agent가 컨테이너 안에서 실행되고 Ollama가 호스트 컴퓨터에서 실행된다면 컨테이너 내부의 localhost는 호스트가 아닙니다. 두 프로세스가 서로 다른 컴퓨터에 있다면 localhost는 더더욱 잘못된 주소입니다.

주소를 바꿀 때는 한 번에 한 요소만 변경하십시오.

curl http://localhost:11434/api/version

curl http://localhost:11434/v1/models

curl http://<ollama-host>:11434/v1/models

첫 번째 호출은 Ollama 서비스 위치를, 두 번째 호출은 호환 경로를, 세 번째 호출은 원격 네트워크 경로를 확인합니다. 원격 주소에서만 실패한다면 방화벽, 포트 공개 범위, Ollama의 수신 주소 설정을 확인해야 합니다. 외부에 포트를 바로 공개하기보다 사설 네트워크나 인증 가능한 터널을 우선 검토하십시오.

원격으로 Prime Agent를 실행할 때 Ollama에 접근하려면 어떻게 해야 하나요?

원격 환경에서는 다음 세 지점을 따로 확인합니다.

Prime Agent가 실행되는 호스트에서 Ollama 주소로 접속할 수 있는지 확인합니다.
Ollama가 외부 요청을 받을 수 있는 수신 주소와 포트인지 확인합니다.
SSH 세션이 끊겨도 Ollama와 Prime Agent의 백그라운드 서비스가 계속 살아 있는지 확인합니다.

Ollama 로그는 운영체제에 따라 위치가 다릅니다. 맥에서는 ~/.ollama/logs/server.log, 리눅스 서비스에서는 journalctl -u ollama, 컨테이너에서는 docker logs로 확인할 수 있습니다. Ollama 공식 장애 대응 문서에 나온 로그 위치와 현재 실행 방식이 일치하는지 대조하십시오.

API 호환 필드 분리

연결은 되지만 다음과 같은 오류가 나온다면 단순한 모델 불일치로 결론 내리지 마십시오.

developer role is not supported
reasoning_effort is not supported
스트리밍 응답의 사용량 필드 거부
도구 호출 형식 또는 tool_choice 처리 실패

Ollama의 OpenAI 호환 API는 여러 채팅 필드를 지원하지만, 모든 호환 서버와 모든 모델이 같은 동작을 보장하는 것은 아닙니다. Prime Agent 계열 설정에서는 공급자 전체에 적용하는 compat와 특정 모델에만 적용하는 compat를 나눌 수 있습니다.

예를 들어 서버가 개발자 역할과 추론 강도 필드를 받지 않는 경우 다음처럼 설정할 수 있습니다.

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false
      },
      "models": [
        {
          "id": "qwen2.5-coder:7b",
          "reasoning": false
        }
      ]
    }
  }
}

공급자 수준 설정은 해당 Ollama 공급자의 모든 모델에 적용합니다. 반면 모델 수준 설정은 특정 모델만 덮어씁니다. 따라서 여러 모델을 함께 쓰는 팀이라면 먼저 공급자 수준을 최소 변경하고, 문제가 특정 모델에만 나타날 때 모델 수준으로 좁히는 편이 좋습니다. 공식 사용자 지정 모델 문서의 현재 필드명을 그대로 사용하십시오.

수정 후에는 매번 하나의 값만 바꾸고 다음 순서로 재호출합니다.

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ollama" \
  -d '{
    "model": "<실제 모델 ID>",
    "messages": [
      {"role": "user", "content": "간단한 연결 확인입니다."}
    ],
    "stream": false
  }'

응답이 성공하면 Prime Agent 로그와 Ollama 로그에 같은 요청 시각과 모델 ID가 남는지 비교합니다. 한쪽 로그만 보인다면 애플리케이션 내부 설정 또는 네트워크 경계가 아직 남아 있는 것입니다.

대화 성공과 코딩 성공 분리

Ollama에서는 대화가 되는데 Prime Agent가 코딩 작업을 끝내지 못하면 어떻게 해야 하나요?

텍스트가 한 번 반환되었다는 사실은 파일 도구, 셸 명령, 오류 수정, 장기 문맥을 안정적으로 처리한다는 뜻이 아닙니다. 모델 능력 문제인지 권한 문제인지 다음처럼 작은 단계로 나눠야 합니다.

읽기: 특정 파일 한 개의 내용을 확인하게 합니다.
작은 수정: 주석이나 테스트 문자열처럼 되돌리기 쉬운 변경을 요청합니다.
명령 실행: 상태 확인이나 단일 테스트 명령을 실행하게 합니다.
오류 수정: 의도적으로 만든 작은 실패를 진단하게 합니다.
짧은 반복 작업: 읽기, 수정, 테스트를 한 번의 짧은 흐름으로 연결합니다.

읽기 단계부터 실패하면 작업 폴더 권한이나 Prime Agent의 실행 위치를 확인합니다. 읽기와 수정은 되지만 명령 실행이 틀리면 셸 권한, 명령 해석, 모델의 도구 호출 능력을 나눠 봐야 합니다. 모든 단계에서 모델이 도구를 호출하지 않고 성공했다고 말한다면 성공으로 기록하지 마십시오. 실제 파일 변경과 테스트 결과만 통과 증거로 인정해야 합니다.

실패가 같은 단계에서 반복되면 compat를 계속 늘리는 것보다 모델을 바꾸거나 작업 범위를 줄이는 편이 낫습니다. 이는 Prime Agent 또는 Ollama의 확정된 결함이라고 단정할 수 없는 영역입니다. 모델별 도구 사용 능력과 지시 따르기 성능은 다르며, 일반 대화 성공만으로 장기 코딩 작업을 보장할 수 없습니다.

멈춤과 단절의 시간선

긴 작업이 멈추면 네트워크 하나로 설명하지 마십시오. 다음 시간선을 기록하면 원인을 좁히기 쉽습니다.

시작 직후 지연: 모델을 처음 메모리에 올리는 단계인지 확인합니다.
문맥이 길어진 뒤 지연: 대화와 작업 기록이 커져 처리 자원이 부족해졌는지 확인합니다.
여러 하위 작업을 시작한 뒤 지연: 동시 실행 수와 각 모델 프로세스를 확인합니다.
터미널을 닫은 뒤 중단: Prime Agent 세션과 Ollama 프로세스가 모두 지속되는지 확인합니다.
간헐적 503 또는 응답 중단: 서버 과부하와 자원 고갈을 로그로 확인합니다.

Ollama 공식 안내도 요청이 너무 많으면 서버가 과부하 상태를 나타내는 503 응답을 반환할 수 있다고 설명합니다. 실행 중인 모델은 다음 명령으로 확인할 수 있습니다.

curl http://localhost:11434/api/ps

Prime Agent 쪽에서는 다음 명령으로 세션 상태와 재연결 가능성을 확인합니다.

prime-agent agents
prime-agent status
prime-agent attach <세션 이름>

Prime Agent는 데몬 기반 세션과 재연결을 지원하지만, 이것이 모델 서버의 자원 부족까지 해결해 주지는 않습니다. 장기 실행 및 백그라운드 동작 문서를 기준으로 세션, 워커, 커널의 생존 여부를 따로 확인해야 합니다.

수정 후 최소 검수선

복구를 완료했다고 기록하려면 복잡한 한 번의 작업만 성공시켜서는 부족합니다. 다음 순서로 통과 여부를 남기십시오.

모델 목록에 실제 Ollama 모델 ID가 표시됩니다.
최소 채팅 요청이 정상 응답을 반환합니다.
파일 한 개를 읽습니다.
작은 파일을 수정하고 변경 내용을 확인합니다.
단일 테스트 명령을 실행하고 결과를 읽습니다.
터미널을 분리한 뒤 세션을 다시 연결합니다.
짧은 장기 작업을 중단 후 재개합니다.

각 검수에는 Prime Agent 버전, Ollama 버전, 모델 ID, 실행 호스트, models.json의 민감정보를 제거한 요약, 로그 위치, 실패가 시작된 단계를 함께 기록하십시오. 이 기록이 있어야 다음 업데이트 뒤 같은 장애인지 새 호환성 문제인지 구분할 수 있습니다.

환경 선택 기준

조건	본인 컴퓨터	독립 원격 환경	맥 환경 임대
짧은 모델 확인과 설정 수정	적합	과할 수 있음	필요성 낮음
터미널이 자주 끊기는 장기 작업	불안정할 수 있음	적합	적합
로컬 파일과 물리 장치 접근	가장 적합	제한 가능	사전 확인 필요
팀이 같은 재현 환경을 공유해야 함	관리 부담	적합	구성에 따라 적합
일시적인 테스트와 검증	적합	비용과 관리 검토	빠른 대안
자원 변동이 장애 원인	장비 상태에 좌우	안정성 확인 필요	제공 환경 확인 필요

짧은 실험과 개인 파일 작업은 본인 컴퓨터가 효율적입니다. 반대로 세션 유지, 원격 재접속, 팀 공용 재현성이 중요하면 독립 원격 환경이나 맥 환경 임대를 비교해야 합니다. 물리 장치가 필요하거나 매일 같은 고정 부하를 장기간 유지해야 한다면 임대보다 직접 보유가 더 맞을 수 있습니다.

현재 환경에서 계속 재설치하는 방식은 주소 경계, 자원 부족, 세션 단절을 해결하지 못합니다. 로컬 컴퓨터는 절전과 자원 경쟁에 영향을 받고, 일반 원격 서버는 맥 전용 작업과 세션 관리가 불편할 수 있습니다. 이런 조건에서 일시적인 Prime Agent 검증이나 장기 실행 환경이 필요하다면 맥 미니 임대 환경을 비교 대상으로 올려 두는 것이 합리적입니다. 먼저 다섯 층 검수를 끝낸 뒤에도 자원과 지속성이 문제라면, 설정을 계속 바꾸기보다 안정적인 맥 환경으로 옮길지 판단하십시오.

Prime Agent의 첫 Ollama 연결 절차가 아직 정리되지 않았다면 맥 지원 안내에서 실행 환경을 확인하고, 모델 연결 자체보다 장기 실행 조건이 문제인지 분리해 보시기 바랍니다.