Ollama를 코딩 에이전트에 연결하는 방법

연결 대상

Ollama를 코딩 에이전트와 함께 사용할 수 있으며, 연결 과정은 예상보다 훨씬 간단합니다. 기본 URL(base URL)을 하나 변경하고 모델 이름 하나를 선택하기만 하면 됩니다. API 키 필드에는 여전히 값이 필요하지만, 로컬 서버는 이를 무시하므로 아무 문자열이나 입력해도 됩니다.

Ollama는 11434 포트에서 대기하며 두 가지 형태의 요청을 동시에 처리합니다. /v1/chat/completions는 OpenAI 호환 형태이며, Ollama 문서에서는 해당 키가 필수라고 명시되어 있으나 실제로는 무시됩니다. /v1/messages은 Anthropic 호환 형태이며, Claude Code가 사용하는 방식입니다. 사용 중인 에이전트는 이미 이 두 가지 중 하나를 지원하므로, 다른 설정을 변경할 필요는 없습니다.

이 과정은 5분이면 충분합니다. 결과물의 사용 가능 여부는 거의 아무도 변경하지 않는 두 가지 설정인 컨텍스트 길이(context length)와 유지 시간(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 사이의 환경에서 실제 구동 가능한지 먼저 확인하십시오.

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

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

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

Ollama에 OpenCode 연결하기

~/.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를 자체 호스팅할 수 있는지 여부에서 다룹니다.

Aider를 Ollama에 연결하기

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는 컨텍스트 윈도우를 초과하는 내용을 조용히 폐기합니다. 가장 오래된 토큰부터 삭제되므로, 모델은 더 이상 볼 수 없는 파일에 대해 자신 있게 답변하거나 두 단계 전에 전달한 지시 사항을 잊어버리게 됩니다. 로컬 모델이 코드를 작성하기에 너무 멍청하다는 보고의 대부분은 바로 이 메커니즘 때문입니다.

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 호환 클라이언트는 이를 요청할 수 없습니다. 둘째, 이 설정은 서버 단위로 적용되므로 해당 서버를 가리키는 모든 에이전트가 이 설정을 상속받습니다. 특정 모델에 다른 윈도우 크기가 필요하다면 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는 기본적으로 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와 정반대되는 특징입니다. GPU VPS가 API 토큰 비용 대비 손익분기점을 넘기는 시점에 관련 계산이 나와 있습니다.

반면, 긴 다단계 작업에서는 로컬 모델이 불리합니다. "테스트 실패 원인 파악, 원인 수정, 호출부 업데이트"와 같은 작업은 전체 기록을 컨텍스트에 유지한 채 여러 번의 정확한 도구 호출을 연속으로 수행해야 합니다. 적당한 서버에서 구동되는 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에 모두 올라가지 못한 상태입니다. 컨텍스트 길이를 줄이거나, 더 작은 모델 또는 더 낮은 양자화 모델로 변경하십시오.

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이 권장됩니다. 14B 파라미터 미만의 모델은 코드에 관한 질문에는 잘 답변할 수 있으나, 다단계 편집 작업에서는 실패할 가능성이 큽니다. 에이전트 작업은 도구 호출 시 발생하는 작은 서식 오류에도 민감하기 때문입니다. 샘플 프롬프트보다는 실제 저장소의 작업을 하나 선정하여 테스트하십시오.

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

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