OpenClaw 로컬 LLM 연동 트러블슈팅: N100 홈서버 Ollama + baseUrl 설정 완전정복 (2026)

3줄 요약

• 대상: OpenClaw 로컬 LLM 연동 트러블슈팅: N100 홈서버 Ollama + baseUrl 설정 완전정복 (2026) 내용을 빠르게 파악하려는 독자
• 핵심: 설치·설정·운영 포인트를 핵심 단계 중심으로 정리
• 결과: 재현 가능한 절차와 점검 기준으로 시행착오를 줄임

트러블슈팅

• 증상이 나오면 로그·버전·포트/권한·네트워크 순서로 확인합니다.
• 설정 반영이 안 되면 서비스 재시작/캐시 비우기 후 다시 검증합니다.

결론 + 다음 단계

핵심 절차를 먼저 완료하고, 운영 단계에서는 백업·모니터링·기본 보안 설정을 함께 적용하세요.

• Homelablog 홈에서 관련 가이드 더 보기
• Self Hosting 카테고리 연계 글 보기

3줄 요약

• 대상: OpenClaw 로컬 LLM 연동 트러블슈팅: N100 홈서버 Ollama + baseUrl 설정 완전정복 (2026) 내용을 빠르게 파악하려는 독자
• 핵심: 설치·설정·운영 포인트를 핵심 단계 중심으로 정리
• 결과: 재현 가능한 절차와 점검 기준으로 시행착오를 줄임

트러블슈팅

• 증상이 나오면 로그·버전·포트/권한·네트워크 순서로 확인합니다.
• 설정 반영이 안 되면 서비스 재시작/캐시 비우기 후 다시 검증합니다.

결론 + 다음 단계

핵심 절차를 먼저 완료하고, 운영 단계에서는 백업·모니터링·기본 보안 설정을 함께 적용하세요.

• Homelablog 홈에서 관련 가이드 더 보기
• Self Hosting 카테고리 연계 글 보기

이 글은 N100 홈서버에서 OpenClaw를 로컬 LLM(Ollama)과 연동할 때 자주 막히는 포인트를 ‘원인 → 해결 순서’로 정리한 트러블슈팅이다. 특히 baseUrl, 네트워크/프록시, 모델 라우팅에서 시행착오가 많아 운영 관점에서 정리한다.

이 글의 목표(성공 기준)

• OpenClaw가 Ollama endpoint를 정상적으로 호출한다.
• 로컬/원격 네트워크에서 baseUrl이 꼬이지 않는다.
• 문제 발생 시(타임아웃/연결 거부/모델명 불일치) 점검 순서가 정리되어 있다.

OpenClaw를 쓰다 보면 어느 순간 “모델 비용도 줄이고, 응답도 더 로컬하게 만들고, 민감한 데이터도 밖으로 덜 나가게 하고 싶다”는 욕심이 생깁니다. 그때 가장 현실적인 선택지가 Ollama 같은 로컬 LLM을 붙이는 방식입니다. 그런데 막상 연결하려고 하면 생각보다 자주 같은 지점에서 막힙니다. baseUrl을 어디로 잡아야 하는지, 로컬/원격이 섞일 때 localhost 함정에 빠지지 않는지, 그리고 연결은 됐는데도 툴 호출(tool call)이 깨지거나 응답이 너무 느려지는지 같은 문제들입니다.

이 글은 “OpenClaw 로컬 LLM 연동”을 목표로, (1) 내 맥북/PC에서 OpenClaw를 돌리고 (2) N100 홈서버 같은 원격 머신에서 Ollama를 돌리는 구성을 기준으로 정리합니다. 설치/연동의 최소 절차부터, 연결 테스트 루틴, 그리고 자주 겪는 오류를 원인 → 확인 → 해결 순서로 풀어 드릴게요.

공식 참고: OpenClaw 로컬 모델 문서, Ollama 공식 사이트

baseUrl 빠른 요약

결론부터 말하면, baseUrl은 “OpenClaw가 실행되는 위치”에서 Ollama의 /v1 엔드포인트로 접근 가능한 주소여야 합니다. 여기서 한 번만 정확히 잡으면, 이후 트러블슈팅 난이도가 확 떨어집니다.

연동 흐름을 처음부터 보고 싶다면 OpenClaw + Ollama 연동 가이드도 함께 참고하세요.

OpenClaw 로컬 LLM 연동 10분 체크리스트 (baseUrl 먼저 확인)

처음 붙여보는 분이라면 이 글의 핵심은 OpenClaw 로컬 LLM 연동의 baseUrl을 ‘OpenClaw가 실행되는 위치에서 접근 가능한 주소’로 정확히 잡는 것입니다. OpenClaw 로컬 LLM 연동을 안정화한 뒤에야 모델 선택, tool call 호환성, 성능 튜닝이 의미 있게 따라옵니다.

전체 구성: OpenClaw ↔ (네트워크) ↔ Ollama(로컬 LLM)

이 글에서 다루는 전형적인 홈랩 구성은 아래 2가지입니다.

• 구성 A (가장 단순): OpenClaw와 Ollama가 같은 머신에서 실행 → baseUrl은 http://127.0.0.1:11434/v1로 끝
• 구성 B (실전 홈랩): OpenClaw는 내 PC/맥북, Ollama는 N100 홈서버 → baseUrl은 http://N100의_IP:11434/v1 또는 VPN(Tailscale) 주소

오늘의 핵심은 구성 B입니다. 구성 B에서는 “내가 로컬이라고 생각한 localhost가 사실은 컨테이너 내부 또는 다른 컴퓨터의 localhost”가 되어버리는 순간부터 문제가 시작합니다.

준비물 체크리스트 (10분 컷을 위한 최소 조건)

• OpenClaw가 실행 중인 머신(맥북/PC/서버) 1대
• Ollama를 돌릴 머신 1대 (예: N100 미니PC, 메모리 16GB 이상 권장)
• 두 장비가 서로 통신 가능한 네트워크 (동일 LAN 또는 VPN)
• Ollama에 최소 1개 모델이 pull 되어 있음 (예: qwen2.5:7b 등)

OpenClaw 자체 설치에서 막힌 경우라면, 먼저 아래 글에서 “설치/실행이 되는 상태”를 만든 뒤에 이 글로 돌아오는 게 빠릅니다.

• OpenClaw 설치 트러블슈팅 가이드: 자주 막히는 오류와 해결 순서

N100 홈서버에 Ollama 올리기 (원격 구성을 전제로)

N100은 전력 대비 성능이 좋아서 “항상 켜두는 로컬 LLM 서버”로 많이 씁니다. 다만 GPU가 없거나 약한 경우가 많으니, 모델 선택과 메모리/스왑 설계가 중요합니다. 아래는 홈랩에서 많이 쓰는 2가지 방식입니다.

방법 1) Docker로 Ollama 실행 (운영 편함)

services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    restart: unless-stopped
    ports:
      - "11434:11434"
    volumes:
      - ollama:/root/.ollama
    environment:
      - OLLAMA_HOST=0.0.0.0
volumes:
  ollama:

포인트

• 11434 포트를 외부로 열어야 OpenClaw가 붙습니다.
• OLLAMA_HOST=0.0.0.0 설정이 없으면, 기본값 때문에 127.0.0.1에만 바인딩되어 다른 머신에서 접근이 안 되는 경우가 있습니다.
• 외부 인터넷으로 포트를 노출하는 건 권장하지 않습니다. 가능하면 VPN(Tailscale/WireGuard) 또는 내부망에서만 접근하세요.

방법 2) 네이티브 설치로 Ollama 실행 (성능/호환성 이점)

운영체제에 직접 설치하면 드라이버/권한 이슈가 줄어드는 경우가 있습니다. 다만 환경마다 설치 방식이 달라 여기서는 “작동 확인 루틴”만 확실히 잡아두겠습니다.

# 모델 다운로드(예시)
ollama pull qwen2.5:7b

# 서버가 실제로 살아 있는지 확인
curl http://127.0.0.1:11434/api/tags

원격에서 붙을 계획이라면, N100에서 아래도 함께 확인하세요.

# (OpenAI 호환 엔드포인트) 모델 목록
curl http://127.0.0.1:11434/v1/models

baseUrl 이해하기: “어디에서” 실행 중인지가 전부다

OpenClaw에서 로컬 LLM 연동이 꼬일 때 가장 흔한 원인은 baseUrl을 잘못 잡는 것입니다. 특히 다음 3가지를 먼저 머릿속에 고정하면 해결 속도가 확 올라갑니다.

• OpenClaw가 실행되는 위치에서 보이는 주소가 baseUrl이다.
• Docker 안의 localhost는 호스트의 localhost가 아니다.
• Ollama의 OpenAI 호환 API를 쓰면 보통 /v1 경로가 붙는다.

실전에서 자주 쓰는 baseUrl 패턴은 아래처럼 정리할 수 있습니다.

• 같은 머신: http://127.0.0.1:11434/v1
• 같은 LAN의 다른 머신(N100): http://192.168.0.50:11434/v1 (예시)
• Tailscale 등 VPN: http://100.x.y.z:11434/v1 (Tailscale IP 예시)
• OpenClaw가 Docker 컨테이너: 보통 http://host.docker.internal:11434/v1(Mac/Windows) 또는 호스트 IP 사용

여기서 “연결은 되는데 404가 뜬다”면 /v1 경로 유무를 의심하세요. 반대로 “Connection refused”라면 대부분 포트 바인딩/방화벽/바인드 주소(0.0.0.0) 문제입니다.

OpenClaw 설정 예시: 로컬 provider 등록 + 기본 모델 지정

OpenClaw는 로컬 모델을 OpenAI 호환 endpoint로 다루는 방식이 일반적입니다. 아래 예시는 OpenClaw 공식 문서(로컬 모델 설정)에서 공유되는 형태를 기준으로, 핵심 필드만 남겨 “무슨 뜻인지”가 보이도록 단순화한 것입니다.

{
  "models": {
    "mode": "merge",
    "providers": {
      "local": {
        "baseUrl": "http://N100_IP:11434/v1",
        "apiKey": "ollama-local",
        "api": "openai-responses",
        "models": [
          {
            "id": "qwen2.5:7b",
            "name": "Qwen 2.5 7B",
            "contextWindow": 32768,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "local/qwen2.5:7b"
      }
    }
  }
}

자주 놓치는 지점

• baseUrl: 원격이면 반드시 N100 주소로. 127.0.0.1은 “OpenClaw가 돌고 있는 그 머신”의 루프백입니다.
• apiKey: Ollama는 대개 실제 키 검증을 하지 않더라도, 클라이언트가 필드를 요구하는 경우가 있어 더미 문자열이라도 넣어두면 편합니다.
• gateway 재시작: 설정 파일을 바꿨는데 반영이 안 되면, 대부분 게이트웨이를 재시작해야 합니다.

연결 테스트 루틴: “OpenClaw 문제인지, Ollama 문제인지” 3분 만에 분리하기

연동 디버깅은 순서를 잘 잡으면 빠릅니다. 저는 아래 루틴으로 “네트워크 → Ollama → OpenClaw” 순서로 좁혀갑니다.

1) 네트워크 레벨 확인 (OpenClaw 머신에서 실행)

# N100이 응답하는지
curl http://N100_IP:11434/api/tags

여기서 실패하면 OpenClaw 설정을 만지기 전에 방화벽/포트/바인딩부터 해결해야 합니다.

2) OpenAI 호환 엔드포인트 확인

curl http://N100_IP:11434/v1/models

이게 성공하면 “Ollama는 정상이고, OpenAI 호환 API도 정상”입니다. 그 다음에 OpenClaw 쪽 baseUrl, provider 이름, 모델 ID를 봅니다.

3) OpenClaw에서 모델이 잡히는지 확인

환경에 따라 명령이 조금 다를 수 있지만, 보통은 모델 목록/카탈로그에서 로컬 provider가 등장해야 합니다. 만약 목록에는 뜨는데 실제 실행은 다른 모델로 떨어진다면 “기본 모델 우선순위” 또는 “서브에이전트 모델 선택” 쪽을 확인합니다.

자주 겪는 트러블슈팅 (증상별 빠른 처방)

증상 A) ECONNREFUSED / Connection refused

• 원인 후보: 포트 미오픈, Ollama가 127.0.0.1에만 바인딩, 방화벽 차단
• 확인: OpenClaw 머신에서 curl http://N100_IP:11434/api/tags
• 해결: Docker면 포트 매핑(11434:11434) + OLLAMA_HOST=0.0.0.0, 방화벽 규칙 점검

증상 B) 404 Not Found (특히 /v1 관련)

• 원인 후보: baseUrl에 /v1가 빠졌거나, 반대로 중복으로 들어간 경우
• 확인: curl http://N100_IP:11434/v1/models가 되는지
• 해결: OpenClaw가 요구하는 엔드포인트 규칙에 맞춰 baseUrl을 정리(...:11434/v1)

증상 C) 모델이 없다고 나옴 (model not found)

• 원인 후보: Ollama에 모델을 pull 하지 않음, 모델 ID 오타
• 확인: curl http://N100_IP:11434/api/tags에서 모델 목록 확인
• 해결: ollama pull qwen2.5:7b 등으로 모델 다운로드 후, OpenClaw 설정의 id와 정확히 맞추기

증상 D) 연결은 되는데 툴 호출이 깨짐 (도구 실행 실패, 함수 호출 불가)

• 원인 후보: 모델이 tool calling에 약함, 또는 OpenAI 호환 모드(api)가 맞지 않음
• 확인: 같은 프롬프트를 “단순 질의응답”으로는 되는지, “웹 검색/파일 읽기”처럼 도구가 필요한 작업에서만 깨지는지
• 해결: tool-friendly 모델로 변경(예: Qwen 계열, Llama 3.1 Instruct 등) + OpenClaw 문서의 권장 api 모드 확인

증상 E) 응답이 너무 느림 / 타임아웃

• 원인 후보: N100 CPU 한계, 메모리 부족으로 스왑 지옥, 모델이 너무 큼
• 확인: N100에서 CPU 사용률/메모리/스왑을 함께 확인, 첫 토큰까지 시간이 얼마나 걸리는지 체감
• 해결: 더 작은 모델로 시작(7B 이하), 컨텍스트/출력 토큰 제한, 불필요한 동시에 실행되는 서비스 정리

증상 F) 설정을 바꿨는데 OpenClaw가 그대로임

• 원인 후보: 게이트웨이가 재시작되지 않아 설정이 반영되지 않음
• 확인: “저장”만 했는지, 실제 프로세스 재시작까지 했는지 점검
• 해결: OpenClaw gateway 재시작(서비스/데몬 기준) 후 다시 테스트

운영 팁: 원격 N100을 ‘LLM 전용 노드’로 만들기

로컬 LLM 서버는 설치보다 운영이 더 중요합니다. 특히 N100 같은 저전력 머신은 “적당한 모델 + 안정적인 네트워크 + 예측 가능한 리소스” 조합에서 만족도가 확 올라갑니다.

• 포트 노출 최소화: 11434를 인터넷에 그대로 열지 말고, 가능하면 VPN 뒤로 숨기기
• 리소스 모니터링: 첫 주는 CPU/메모리/스왑만 봐도 병목이 드러남
• 업데이트 루틴: Ollama/모델 업데이트 전에 “작동 확인 curl”을 습관화
• 컨테이너 운영: 여러 스택을 띄운다면 Dockge 같은 대시보드가 편함

Docker 스택을 여러 개 운영 중이라면, 아래 Dockge 글도 함께 보면 “LLM 서버 포함한 스택 관리”가 훨씬 쉬워집니다.

• Dockge 설치 가이드 2026: Proxmox Helper-Scripts로 10분 만에 Docker 스택 관리 시작

원격 접속을 안전하게: LAN + VPN 우선, 공개 포트는 마지막

OpenClaw 로컬 LLM 연동을 “원격 N100”으로 확장할 때, 성능만큼 중요한 게 접근 경로입니다. Ollama는 기본적으로 인증/권한 관리가 강한 서비스가 아니기 때문에, 11434 포트를 그대로 인터넷에 노출하는 방식은 추천하지 않습니다. 대신 아래 우선순위를 기준으로 구성하면 안전성과 문제 해결이 동시에 좋아집니다.

• 1순위: 같은 LAN에서만 접근 (공유기 내부 IP 사용)
• 2순위: VPN(Tailscale/WireGuard)로 “내 기기만” 접근
• 3순위: 리버스 프록시/인증 추가 (정말 필요할 때만)

특히 VPN을 쓰면 baseUrl도 깔끔해집니다. 예를 들어 Tailscale을 쓰는 경우, OpenClaw 머신에서는 http://100.x.y.z:11434/v1처럼 “항상 변하지 않는 주소”로 접속할 수 있어서, 공유기 재부팅이나 DHCP로 IP가 바뀌는 상황에서도 트러블이 줄어듭니다.

Docker에서 흔한 baseUrl 함정 4가지 (로컬 LLM 연동의 80%)

OpenClaw 또는 Ollama 중 하나라도 Docker로 돌리기 시작하면, baseUrl은 거의 항상 한 번은 틀립니다. 아래 4가지만 기억해도 대부분의 삽질을 줄일 수 있어요.

1. 컨테이너 안에서 127.0.0.1는 “컨테이너 자신”입니다. 호스트의 Ollama로 붙고 싶다면, Linux는 호스트 IP를 쓰거나 host 네트워크를 고려해야 합니다.
2. Mac/Windows는 host.docker.internal가 도움이 됨 (OpenClaw가 Docker일 때 특히 유용). 반면 Linux는 기본 제공이 아니라서 직접 라우팅이 필요할 수 있습니다.
3. 포트 매핑 방향 확인: 11434:11434는 “호스트 11434 → 컨테이너 11434”입니다. 반대로 적어두면 연결이 안 됩니다.
4. /v1 경로를 섞어 쓰지 말기: baseUrl에 /v1를 포함했다면, 설정/코드에서 추가로 /v1를 붙이지 않도록 한 번 더 확인합니다.

실전 예시: 맥북 OpenClaw + N100 Ollama + Tailscale로 고정 baseUrl 만들기

“로컬은 편한데, 노트북을 들고 다니면 IP가 바뀌어서 자꾸 끊긴다”는 상황이 많습니다. 이때 VPN을 붙여두면, 홈 밖에서도 같은 baseUrl로 테스트가 가능합니다. 예시는 아래 흐름처럼 잡으면 됩니다.

1. N100과 맥북에 Tailscale 설치
2. N100의 Tailscale IP(100.x.y.z)를 확인
3. OpenClaw 설정의 baseUrl을 http://100.x.y.z:11434/v1로 고정
4. 맥북에서 curl http://100.x.y.z:11434/v1/models로 1차 확인
5. OpenClaw에서 로컬 provider 모델을 기본(primary)으로 지정

이 구성의 장점은 문제를 진단할 때도 큽니다. “집에서는 되는데 회사/카페에서는 안 된다” 같은 이슈가 나오면, 그건 대부분 OpenClaw/Ollama 문제가 아니라 VPN 연결 상태 또는 방화벽 정책 문제로 범위를 좁힐 수 있습니다.

문제 발생 시 체크 포인트: 어디를 보면 바로 원인이 보이나?

연동이 애매하게 실패할 때는 “감”으로 만지기보다, 확인 지점을 고정해두는 편이 빠릅니다. 아래 체크리스트를 순서대로 밟으면 원인 분리가 됩니다.

• OpenClaw 머신: baseUrl로 curl이 되는가? (네트워크 문제인지 먼저 분리)
• N100(Ollama): 모델이 실제로 pull 되어 있는가? (/api/tags 확인)
• OpenClaw 설정: provider 이름과 모델 ID가 정확히 일치하는가?
• 게이트웨이 재시작: 설정 변경 후 재시작을 했는가? (반영 안 됨 이슈 차단)
• 모델 적합성: 단순 Q&A는 되는데 tool call에서만 깨지면 모델/호환 모드부터 의심

마무리: OpenClaw 로컬 LLM 연동은 ‘baseUrl’부터 시작한다

정리하면, OpenClaw 로컬 LLM 연동에서 가장 중요한 것은 “내가 지금 어느 머신에서 무엇을 실행하고 있는가”를 정확히 분리해서 보는 것입니다. baseUrl은 그 분리의 결과물이고, 트러블슈팅의 절반은 baseUrl을 제대로 잡는 순간 끝납니다.

만약 지금도 막힌 지점이 있다면, 아래 3가지만 다시 체크해 보세요.

1. OpenClaw 머신에서 curl http://N100_IP:11434/api/tags가 되는가?
2. curl http://N100_IP:11434/v1/models가 되는가?
3. OpenClaw 설정의 baseUrl이 “OpenClaw가 실행되는 위치에서 접근 가능한 주소”인가?

이 3개가 모두 통과하면, 그 다음은 모델 선택(툴 호출 가능성)과 OpenClaw 내부 모델 우선순위/기본값을 조정하는 단계로 넘어가면 됩니다.

OpenClaw 로컬 LLM 연동 체크리스트 (한 번에 통과하기)

OpenClaw 로컬 LLM 연동에서 가장 많이 틀리는 부분은 baseUrl과 네트워크입니다. OpenClaw가 실행되는 위치에서 Ollama의 /v1 엔드포인트가 curl로 열리는지, 그리고 설정 변경 후 게이트웨이를 재시작했는지부터 확인하면 대부분의 트러블이 빠르게 정리됩니다.

N100 홈서버 Ollama 운영 팁: 느려질 때 먼저 의심할 것

N100 홈서버에서 Ollama를 운영할 때는 모델 크기와 메모리, 스왑 사용량이 체감 성능을 좌우합니다. 응답이 느려지면 먼저 작은 모델로 OpenClaw 로컬 LLM 연동을 안정화한 뒤, 필요할 때만 단계적으로 모델을 키우는 편이 실패 확률이 낮습니다.