코딩 에이전트와 Ollama 연결 및 설정 가이드

연결 대상

코딩 에이전트와 Ollama를 연결하는 과정은 생각보다 간단합니다. 기본 URL을 하나 변경하고 모델 이름을 하나 선택하면 됩니다. API 키 필드에는 여전히 값을 입력해야 하지만, 로컬 서버는 이를 무시하므로 아무 문자열이나 입력해도 됩니다.

Ollama는 11434 포트에서 대기하며 두 가지 요청 형식을 동시에 처리합니다. /v1/chat/completions는 OpenAI 호환 형식이며, Ollama 문서에 따르면 이곳의 키는 필수 항목이지만 실제로는 무시됩니다. /v1/messages은 Claude Code가 사용하는 Anthropic 호환 형식입니다. 에이전트가 이미 이 두 형식 중 하나를 지원하므로 다른 설정은 변경할 필요가 없습니다.

이 과정은 5분이면 충분합니다. 결과물이 실제로 사용 가능한지는 거의 아무도 변경하지 않는 두 가지 설정인 컨텍스트 길이와 keep-alive, 그리고 모델이 잘 수행할 수 있는 작업을 할당하는지에 달려 있습니다. 두 설정은 각각 별도의 섹션에서 다루며, 솔직한 한계점은 마지막에 정리했습니다.

로컬 베이스 URL을 허용하는 코딩 에이전트

테스트는 간단합니다. 해당 도구가 베이스 URL 설정을 노출하는가 하는 점입니다. 설정이 있다면 사용자의 서버와 통신할 수 있습니다.

Ollama는 Claude Code, OpenCode, Codex, Cline, Roo Code, Zed, JetBrains IDE 및 VS Code를 위한 통합 페이지를 제공합니다. Aider는 자체적인 Ollama 지원 문서를 별도로 제공합니다. 2026년 8월 기준으로 사람들이 코딩 에이전트라고 부르는 대부분의 도구가 여기에 해당합니다. 이들은 모두 동일한 규격을 사용하지 않으며, 이러한 차이로 인해 설정 과정에서 오류가 발생합니다.

• 대부분의 에이전트는 OpenAI 호환 엔드포인트를 원합니다. 베이스 URL http://localhost:11434/v1과 비어 있지 않은 임의의 API 키 문자열을 입력하십시오.
• Claude Code는 OpenAI 베이스 URL을 전혀 허용하지 않습니다. Anthropic Messages API를 사용하므로 ANTHROPIC_BASE_URL을 http://localhost:11434로 설정해야 하며, Ollama는 이를 /v1/messages에서 서비스합니다.
• Codex는 OpenAI Responses API를 사용합니다. Ollama는 버전 0.13.3에서 추가된 /v1/responses로도 이를 서비스합니다.
• 베이스 URL 설정이 없는 에이전트는 엔드포인트가 클라이언트에 내장되어 있어 리다이렉트할 수 없습니다. 대신 자체 호스팅 LiteLLM 게이트웨이와 같은 변환 계층을 앞에 두고, 클라이언트가 요구하는 형식으로 모델을 다시 노출하십시오.

Ollama는 이러한 설정을 대신 작성해 줄 수 있습니다. ollama launch opencode는 선택한 모델에 대한 인라인 설정을 포함하여 OpenCode를 실행하고, ollama launch claude은 Claude Code에 대해 동일한 작업을 수행하며, ollama launch droid --config는 도구를 실행하지 않고 설정 파일만 작성합니다.

Ollama 설치 및 도구 호출 가능 모델 내려받기

curl -fsSL https://ollama.com/install.sh | sh
systemctl status ollama --no-pager
ollama pull qwen3-coder:30b
ollama ls

설치 프로그램이 systemd 유닛을 추가하고 서비스를 시작하므로 systemctl status ollama 명령은 active (running)을 출력해야 합니다. 만약 출력되지 않는다면 journalctl -e -u ollama 명령으로 원인을 확인할 수 있습니다.

에이전트는 도구 호출(tool calling)을 통해 작동하므로 모델은 반드시 이 기능을 지원해야 합니다. 에이전트는 파일을 읽고, 패치를 작성하고, 테스트를 실행한 뒤, 실패 내용을 읽고 다시 시도하는 과정을 거칩니다. 도구 호출을 생성하지 못하는 모델은 수정 사항을 직접 적용하는 대신 산문으로 설명하려 들며, 이 경우 에이전트는 무한 루프에 빠지거나 멈추게 됩니다. 모델을 내려받기 전에 ollama.com의 모델 페이지에서 tools 레이블이 있는지 확인하십시오. qwen3-coder:30b 모델은 이 기능을 지원하며, 2026년 8월 기준으로 해당 태그는 19 GB 용량에 256K 컨텍스트 윈도우를 제공합니다. 서버가 CPU 전용이거나 RAM이 부족하다면, VPS에서 Qwen 27B 태그를 위한 메모리 계산 문서를 참고하여 8 GB에서 64 GB 사이의 환경에서 실제로 구동 가능한지 먼저 확인하십시오. 모델을 내려받으면 해당 기가바이트 단위의 데이터가 서버의 루트 디스크에 저장됩니다. 루트 디스크는 VPS에서 가장 용량이 부족하기 쉬운 공간이므로, 디스크가 가득 차기 전에 Ollama의 모델 파일 저장 위치와 이동 방법을 읽어두는 것이 좋습니다.

이제 서버에서 실제로 제공하는 모델 이름을 확인합니다.

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

응답에 포함된 문자열은 에이전트 설정 파일에 한 글자도 틀리지 않고 정확히 입력되어야 합니다. 이 과정을 먼저 확인하면 대부분의 모델을 찾을 수 없다는 오류를 방지할 수 있습니다. Ollama가 아직 설치되지 않았다면 VPS에서 Ollama로 LLM 직접 호스팅하기의 상세 가이드를 참조하십시오.

OpenCode를 Ollama에 연결하기

~/.config/opencode/opencode.json을 다음과 같이 수정합니다:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder:30b": {
          "name": "qwen3-coder 30b"
        }
      }
    }
  }
}

models 아래의 키는 Ollama로 전송되는 모델 이름이므로, ollama ls와 정확히 일치해야 합니다. name 필드는 모델 선택기에서 표시되는 레이블일 뿐입니다. opencode를 시작하고 Ollama 공급자로 전환한 뒤, journalctl -e -u ollama를 모니터링하여 요청이 다른 곳이 아닌 서버에 정상적으로 도착했는지 확인하십시오. 에이전트 자체를 설정하는 방법은 VPS에서 OpenCode 실행하기에서 다룹니다.

Claude Code를 Ollama에 연결하기

export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434
claude --model qwen3-coder:30b

ANTHROPIC_API_KEY은 의도적으로 빈 문자열로 설정합니다. 환경 변수에 실제 키가 남아 있으면 요청이 호스팅된 API로 전송되어 로컬 추론 대신 비용이 청구될 수 있습니다. ollama launch claude은 이 모든 설정을 자동으로 처리합니다.

호환성 계층에서 지원하지 않는 기능을 숙지하십시오. 이 계층은 tool_choice이나 프롬프트 캐싱을 구현하지 않으며, 토큰 계산 엔드포인트도 없습니다. 따라서 표시되는 토큰 수는 모델 자체 토크나이저를 기반으로 한 근사치입니다. Claude Code는 대규모 시스템 프롬프트와 방대한 도구 세트를 함께 제공하므로 일반적인 채팅 클라이언트보다 더 많은 컨텍스트가 필요합니다. 무엇이 호환되고 무엇이 그렇지 않은지에 대한 더 자세한 내용은 Claude를 자체 호스팅할 수 있는지 여부에서 다룹니다.

Ollama에 Aider 연결하기

export OLLAMA_API_BASE=http://127.0.0.1:11434
aider --model ollama_chat/qwen3-coder:30b

Aider 문서에서는 ollama/ 대신 ollama_chat/ 접두사 사용을 권장합니다. 또한 .aider.model.settings.yml에서 모델별로 컨텍스트 윈도우를 고정할 수 있는데, 이는 특정 모델이 서버 기본값과 다른 윈도우 크기를 요구할 때 유용합니다.

- name: ollama_chat/qwen3-coder:30b
  extra_params:
    num_ctx: 65536

작동 중인 설정에서 엉뚱한 결과가 나오는 이유

이 섹션이 핵심입니다. Ollama는 감지된 VRAM(GPU의 비디오 메모리) 용량을 바탕으로 기본 컨텍스트 길이를 선택하며, 해당 기본값은 다음과 같이 공개되어 있습니다.

[
  {
    "label": "Under 24 GiB VRAM",
    "default_context_tokens": "4,096"
  },
  {
    "label": "24 to 48 GiB VRAM",
    "default_context_tokens": "32,768"
  },
  {
    "label": "48 GiB VRAM or more",
    "default_context_tokens": "262,144"
  }
]

대부분의 VPS 플랜과 모든 CPU 전용 서버는 첫 번째 행인 4,096 토큰에 해당합니다. 대형 GPU를 장착한 경우에만 마지막 행의 262,144 토큰을 사용할 수 있습니다.

에이전트는 작업을 시작하기 전에 이미 4096 토큰을 소모합니다. 시스템 프롬프트, 도구 정의, 저장소 목록, 그리고 처음 여는 파일만으로도 이미 이 용량을 초과합니다. 그다음 발생하는 문제가 바로 핵심입니다. 오류가 발생하지 않는다는 점입니다. Aider 문서에 따르면 Ollama는 컨텍스트 창을 초과하는 내용을 조용히 폐기합니다. 가장 오래된 토큰부터 삭제되므로, 모델은 더 이상 볼 수 없는 파일에 대해 자신 있게 답변하거나 두 단계 전에 내린 지시를 잊어버립니다. 로컬 모델이 코드를 작성하기에 너무 멍청하다는 대부분의 보고는 바로 이 메커니즘 때문입니다. 숫자 자체를 선택하는 것은 사용자의 결정이며, 각 크기별 KV 캐시 메모리에서 num_ctx가 차지하는 비용을 읽어보고 결정하는 것이 좋습니다.

Ollama 문서에서는 에이전트나 코딩 도구와 같은 작업의 경우 최소 64000 토큰으로 설정할 것을 권장합니다. 서버에서 다음과 같이 설정하십시오.

sudo systemctl edit ollama.service

override 파일에 다음 줄을 추가하십시오.

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"

그런 다음 설정을 다시 불러오고 서비스를 재시작하십시오.

sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama ps

ollama ps가 확인 방법입니다. 이 명령은 CONTEXT 열을 출력하며, 해당 숫자가 모델이 실제로 수신한 토큰 수입니다. ID와 SIZE는 서로 다를 것입니다.

NAME               ID              SIZE     PROCESSOR    CONTEXT    UNTIL
qwen3-coder:30b    a1b2c3d4e5f6    24 GB    100% GPU     64000      4 minutes from now

에이전트가 아닌 서버 측에서 설정해야 하는 이유는 두 가지입니다. OpenAI 채팅 완성 스키마에는 컨텍스트 길이를 위한 필드가 없으므로, OpenAI 호환 클라이언트는 이를 요청할 수 없습니다. 또한 이 설정은 서버 단위로 적용되므로 해당 서버를 가리키는 모든 에이전트가 이 설정을 상속받습니다. 출력 측에는 별도의 제한이 있으며, 컨텍스트 길이와 달리 호환성 엔드포인트를 통해 전달되므로 패치 도중 응답이 중간에 끊긴다면 num_predict 및 이에 매핑되는 max_tokens 필드를 조정해야 합니다. 특정 모델에 다른 창 크기가 필요하다면 Modelfile을 사용하여 별도의 복사본을 만드십시오.

FROM qwen3-coder:30b
PARAMETER num_ctx 65536

ollama create qwen3-coder-64k -f Modelfile

컨텍스트는 공짜가 아닙니다. 창이 길어질수록 더 많은 메모리가 필요하므로 PROCESSOR 열을 주의 깊게 살펴보십시오. 100% GPU이 목표로 하는 상태입니다. 모델의 일부가 CPU로 넘어가면 토큰 처리 속도가 급격히 떨어져 에이전트 루프를 사용할 수 없게 되며, 로컬 LLM의 초당 토큰 수 측정을 통해 서버의 실제 한계를 파악할 수 있습니다. 구매 전 장비 사양을 결정하는 방법은 코딩 에이전트용 VPS에 필요한 RAM 및 CPU 사양에서 다룹니다.

요청 간 모델 유지하기

기본적으로 Ollama는 마지막 요청 후 5분이 지나면 모델을 메모리에서 해제합니다. 이는 챗봇에는 적합하지만 에이전트 작업에는 부적절합니다. diff를 읽느라 잠시 멈추면 타이머가 만료되고, 다음 요청 시 수십 기가바이트의 가중치를 디스크에서 다시 불러오느라 첫 토큰이 생성되기까지 지연이 발생합니다. 이는 마치 시스템이 멈춘 것처럼 보입니다.

OLLAMA_KEEP_ALIVE은 10m나 24h과 같은 시간 문자열, 단순히 초 단위의 숫자, 모델을 무기한 유지하기 위한 -1, 또는 즉시 해제하기 위한 0를 인자로 받습니다. 이를 컨텍스트 길이 설정 옆에 배치하십시오.

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"
Environment="OLLAMA_KEEP_ALIVE=-1"

keep_alive 요청 필드는 Ollama의 네이티브 /api/generate 및 /api/chat 엔드포인트에만 존재하며 호환성 엔드포인트에는 없으므로, 에이전트가 요청별로 이를 설정할 수는 없습니다. 환경 변수가 유일한 제어 수단입니다. 메모리를 회수해야 할 때는 ollama stop qwen3-coder:30b을 사용하여 서버를 중단하지 않고 모델을 해제할 수 있습니다. 이 설정을 재부팅 후에도 유지하고 싶거나, 하루 종일 가중치를 메모리에 유지하는 것과 메모리 회수 사이에서 고민 중이라면 Ollama 모델을 메모리에 계속 유지하는 방법을 참고하십시오.

별도 서버에서 Ollama 실행하기

Ollama는 기본적으로 localhost에 바인딩됩니다. 다른 머신에서 접근하려면 동일한 systemd override 파일에 OLLAMA_HOST=0.0.0.0:11434을 설정하고 서비스를 재시작하십시오.

이 작업은 반드시 사설 네트워크 환경에서만 수행하십시오. Ollama 문서에 따르면 로컬 API는 인증을 요구하지 않으므로, 11434 포트를 인터넷에 개방하면 누구나 사용자의 하드웨어를 사용하고 에이전트가 전송하는 모든 데이터를 읽을 수 있습니다. 안전한 방법은 두 가지입니다. 첫 번째는 바인딩을 localhost로 유지하고 노트북에서 SSH를 통해 포트를 포워딩하는 것입니다.

ssh -N -L 11434:localhost:11434 you@your-vps

사용자의 에이전트는 계속해서 http://localhost:11434/v1을 가리키며, 내부적으로 어떤 차이가 있는지 알지 못합니다. 다른 방법은 VPN을 사용하는 것으로, Ollama를 0.0.0.0 대신 VPN 주소에 바인딩합니다. 여러 사람이나 여러 에이전트가 하나의 서버를 공유할 경우, Ollama의 스케줄러는 해당 부하를 처리하도록 설계되지 않았으므로 Ollama와 vLLM 비교 문서를 통해 처리량 차이가 발생하는 지점을 확인하십시오.

로컬 코딩 모델이 유리한 경우와 그렇지 않은 경우

직접 호스팅하는 모델로 구동하는 에이전트가 모든 작업에서 Frontier API를 대체할 수는 없습니다. 로컬 모델은 다음 네 가지 작업에서 확실한 우위를 점합니다.

• 대량의 기계적 편집: 각 변경 사항이 작고 직접 검토할 수 있는 경우입니다. 저장소 전체의 이름 변경, 타입 힌트 추가, docstring 작성, 주석 번역 등이 해당합니다. 모델을 몇 시간 동안 실행해도 비용이 발생하지 않습니다.
• 하드웨어를 벗어나면 안 되는 작업: 기밀 유지 계약이 적용된 클라이언트 코드나 제3자에게 전송이 금지된 내부 저장소 작업이 여기에 해당합니다.
• 오프라인 및 망 분리 환경: 호출할 수 있는 호스팅 API가 전혀 없는 환경입니다.
• 예측 가능한 비용: 서버 비용을 지불하고 나면, 루프를 돌며 토큰을 소모하는 에이전트는 추가 비용이 들지 않습니다. 이는 종량제 API와 정반대입니다. API 토큰 대비 GPU VPS의 손익분기점에 관련 계산이 나와 있습니다.

반면, 긴 다단계 작업에서는 성능이 떨어집니다. "테스트 실패 원인을 찾고, 원인을 수정하고, 호출부를 업데이트하라"는 작업은 전체 이력을 문맥으로 유지하면서 정확한 도구 호출을 연속으로 수행해야 합니다. 적당한 서버에서 구동되는 8B에서 14B 범위의 모델은 잘못된 형식의 도구 호출을 생성하거나 몇 번의 턴이 지나면 계획을 잊어버리며, 결국 작업을 직접 수행하는 것보다 모델을 제어하는 데 더 많은 시간을 쓰게 됩니다. 이는 프롬프트 작성으로 해결할 수 있는 문제가 아니라 모델의 용량 문제입니다.

또한, 잘못된 결과가 치명적이고 모든 줄을 검토할 수 없는 경우에도 로컬 모델은 부적합합니다. 로컬 모델에는 출력을 검증할 수 있는 좁은 범위의 작업을 맡기고, 단계별로 검토하기 어려운 작업에는 호스팅된 모델을 사용하는 것이 좋습니다.

실패 유형 및 확인 가능한 메시지

curl: (7) Failed to connect to localhost port 11434 after 0 ms: Connection refused. 서버가 실행 중이지 않거나 에이전트가 다른 호스트를 가리키고 있습니다. systemctl status ollama을 실행한 뒤 journalctl -e -u ollama를 실행하십시오.

에이전트가 모델이 존재하지 않는다고 보고합니다. 설정 파일에 기재된 이름이 서버에서 제공하는 이름과 일치하지 않습니다. curl http://localhost:11434/v1/models의 결과와 비교하여 해당 문자열을 복사하십시오. 태그는 이름의 일부이므로, 설치하지 않은 태그를 설정 파일에 기재하면 유사한 모델이 설치되어 있더라도 실패합니다.

에이전트가 산문으로 답변하고 파일을 수정하지 않습니다. 모델이 도구를 지원하지 않거나, 요청 내용과 도구 정의가 이미 컨텍스트 윈도우를 가득 채운 경우입니다. 모델 페이지의 tools 라벨을 확인한 뒤, ollama ps의 CONTEXT 열을 확인하십시오.

첫 토큰이 나오기 전 긴 침묵이 있고 이후 정상 속도로 동작합니다. 킵얼라이브(keep-alive) 시간이 만료되어 가중치를 디스크에서 다시 읽어오는 중입니다. OLLAMA_KEEP_ALIVE을 설정하십시오.

모델이 방금 읽은 파일의 내용과 모순된 답변을 합니다. 컨텍스트가 잘렸기 때문입니다. 환경 변수가 systemd 유닛이 아닌 셸에 적용되었을 가능성이 높으므로, ollama ps을 확인하면 보통 설정한 값보다 작은 CONTEXT 값이 나타납니다.

모든 기능은 작동하지만 속도가 느리고, PROCESSOR이 100% GPU이 아닙니다. 모델과 컨텍스트가 VRAM에 모두 들어가지 않는 상태입니다. 컨텍스트 길이를 줄이거나, 더 작은 모델 또는 더 낮은 양자화(quantisation) 모델로 변경하십시오. 다시 내려받기 전에 q4_K_M, q8_0, fp16 각각의 메모리 점유량과 품질 저하 지점을 참조하면, 한 단계 낮출 때 확보되는 여유 공간과 그에 따른 손실을 파악할 수 있습니다.

FAQ

Claude Code를 Ollama에 연결할 수 있습니까?

네, 가능하지만 OpenAI 호환 URL을 사용해서는 안 됩니다. Claude Code는 Anthropic Messages API를 사용하며, Ollama는 동일한 11434 포트의 /v1/messages에서 해당 API 형식을 지원합니다. ANTHROPIC_BASE_URL=http://localhost:11434, ANTHROPIC_AUTH_TOKEN=ollama를 내보내고 ANTHROPIC_API_KEY를 비워둔 뒤 claude --model qwen3-coder:30b으로 실행하십시오. ollama launch claude을 사용하면 동일한 설정을 자동으로 작성할 수 있습니다. 이 호환 계층은 tool_choice이나 프롬프트 캐싱을 구현하지 않으며 토큰 계산 엔드포인트도 없으므로, 표시되는 토큰 수는 근사치입니다.

로컬 모델이 왜 볼 수 없는 코드에 대해 답변합니까?

요청이 컨텍스트 윈도우를 초과하여 가장 오래된 부분이 오류 없이 삭제되었기 때문입니다. Ollama는 감지된 VRAM 용량에 따라 기본 컨텍스트를 설정하며, 24 GiB 미만에서는 기본값이 4,096 토큰입니다. 이는 에이전트의 시스템 프롬프트와 도구 정의만으로도 초과되는 양입니다. systemd 유닛에 OLLAMA_CONTEXT_LENGTH=64000를 설정하고 Ollama를 재시작한 뒤, ollama ps의 CONTEXT 열에서 새로운 값이 적용되었는지 확인하십시오.

VPS에서 코딩 에이전트를 위해 어떤 모델을 실행해야 합니까?

64k 컨텍스트 윈도우를 유지하면서 메모리에 적재 가능한 tools 레이블이 붙은 모델 중 가장 큰 것을 선택하십시오. 코드 최적화 모델을 우선하는 것이 좋습니다. 충분한 VRAM을 갖춘 GPU 서버라면 보통 qwen3-coder:30b이 권장됩니다. 해당 태그가 서버 사양에 비해 너무 크다면, 다운로드 전 Nemotron 3.5 Lightning의 RAM 수치 및 CPU 전용 속도를 비교 자료로 활용하십시오. 14B 파라미터 미만의 모델은 코드 관련 질문에는 잘 답변할 수 있으나, 에이전트 작업은 도구 호출 시 작은 서식 오류에도 민감하므로 다단계 편집 작업에서는 실패할 가능성이 큽니다. 샘플 프롬프트 대신 실제 저장소의 작업을 하나 선택하여 테스트하십시오.

자체 모델에서 코딩 에이전트를 실행하려면 GPU가 필요합니까?

실제로는 그렇습니다. CPU 전용 추론도 가능하며 단일 질문에는 적합하지만, 에이전트는 작업당 여러 요청을 보내고 각 요청마다 긴 기록을 다시 읽어야 하므로 토큰 생성 속도가 느리면 2분짜리 작업이 1시간으로 늘어납니다. ollama ps의 PROCESSOR 열을 확인하십시오. 100% GPU 이외의 값이 표시된다면 모델의 일부가 CPU에서 실행 중이라는 의미이며, 토큰 생성 속도가 급격히 떨어집니다.