Ollama

로컬 및 LAN Ollama 호스트에는 실제 bearer 토큰이 필요하지 않습니다. OpenClaw는 루프백, 사설 네트워크, .local, 그리고 단순 호스트 이름 Ollama 기본 URL에만 로컬 ollama-local 마커를 사용합니다.

원격 공개 호스트와 Ollama Cloud(https://ollama.com)에는 OLLAMA_API_KEY, 인증 프로필, 또는 provider의 apiKey를 통한 실제 자격 증명이 필요합니다.

api: "ollama"를 설정하는 사용자 지정 provider ID도 같은 규칙을 따릅니다. 예를 들어 사설 LAN Ollama 호스트를 가리키는 ollama-remote provider는 apiKey: "ollama-local"을 사용할 수 있으며, 하위 에이전트는 이를 누락된 자격 증명으로 처리하는 대신 Ollama provider 훅을 통해 해당 마커를 해석합니다. 메모리 검색도 agents.defaults.memorySearch.provider를 해당 사용자 지정 provider ID로 설정하여 임베딩이 일치하는 Ollama 엔드포인트를 사용하도록 할 수 있습니다.

auth-profiles.json은 provider ID의 자격 증명을 저장합니다. 엔드포인트 설정(baseUrl, api, 모델 ID, 헤더, 타임아웃)은 models.providers.<id>에 넣으세요. { "ollama-windows": { "apiKey": "ollama-local" } } 같은 오래된 평면 인증 프로필 파일은 런타임 형식이 아닙니다. openclaw doctor --fix를 실행해 백업과 함께 표준 ollama-windows:default API 키 프로필로 다시 작성하세요. 해당 파일의 baseUrl은 호환성 잡음이며 provider 구성으로 옮겨야 합니다.

Ollama를 메모리 임베딩에 사용할 때 bearer 인증은 선언된 호스트로 범위가 제한됩니다.

• provider 수준 키는 해당 provider의 Ollama 호스트에만 전송됩니다.
• agents.*.memorySearch.remote.apiKey는 해당 원격 임베딩 호스트에만 전송됩니다.
• 순수한 OLLAMA_API_KEY 환경값은 Ollama Cloud 관례로 처리되며, 기본적으로 로컬 또는 자체 호스팅 호스트에는 전송되지 않습니다.

Ollama가 Gateway와 같은 machine에서 실행되고 OpenClaw가 설치된 model을 자동으로 발견하도록 하려면 이 방법을 사용하세요.

ollama serve
ollama pull gemma4
export OLLAMA_API_KEY="ollama-local"
openclaw models list --provider ollama
openclaw models set ollama/gemma4

이 경로는 config를 최소화합니다. model을 수동으로 정의하려는 경우가 아니라면 models.providers.ollama block을 추가하지 마세요.

LAN host에는 네이티브 Ollama URL을 사용하세요. /v1을 추가하지 마세요.

{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://gpu-box.local:11434",
        apiKey: "ollama-local",
        api: "ollama",
        timeoutSeconds: 300,
        contextWindow: 32768,
        maxTokens: 8192,
        models: [
          {
            id: "qwen3.5:9b",
            name: "qwen3.5:9b",
            reasoning: true,
            input: ["text"],
            params: {
              num_ctx: 32768,
              thinking: false,
              keep_alive: "15m",
            },
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "ollama/qwen3.5:9b" },
    },
  },
}

contextWindow는 OpenClaw 쪽 context budget입니다. params.num_ctx는 요청을 위해 Ollama로 전송됩니다. 하드웨어가 model의 광고된 전체 context를 실행할 수 없을 때는 둘을 맞춰 두세요.

로컬 daemon을 실행하지 않고 호스팅된 Ollama model을 직접 사용하려는 경우 이 방법을 사용하세요.

export OLLAMA_API_KEY="your-ollama-api-key"

{
  models: {
    providers: {
      ollama: {
        baseUrl: "https://ollama.com",
        apiKey: "OLLAMA_API_KEY",
        api: "ollama",
        models: [
          {
            id: "kimi-k2.5:cloud",
            name: "kimi-k2.5:cloud",
            reasoning: false,
            input: ["text", "image"],
            contextWindow: 128000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "ollama/kimi-k2.5:cloud" },
    },
  },
}

로컬 또는 LAN Ollama daemon이 ollama signin으로 로그인되어 있고 로컬 model과 :cloud model을 모두 제공해야 하는 경우 이 방법을 사용하세요.

ollama signin
ollama pull gemma4

{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://127.0.0.1:11434",
        apiKey: "ollama-local",
        api: "ollama",
        timeoutSeconds: 300,
        models: [
          { id: "gemma4", name: "gemma4", input: ["text"] },
          { id: "kimi-k2.5:cloud", name: "kimi-k2.5:cloud", input: ["text", "image"] },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: "ollama/gemma4",
        fallbacks: ["ollama/kimi-k2.5:cloud"],
      },
    },
  },
}

Ollama server가 둘 이상이면 사용자 지정 공급자 ID를 사용하세요. 각 공급자는 자체 host, model, auth, timeout, model 참조를 갖습니다.

{
  models: {
    providers: {
      "ollama-fast": {
        baseUrl: "http://mini.local:11434",
        apiKey: "ollama-local",
        api: "ollama",
        contextWindow: 32768,
        models: [{ id: "gemma4", name: "gemma4", input: ["text"] }],
      },
      "ollama-large": {
        baseUrl: "http://gpu-box.local:11434",
        apiKey: "ollama-local",
        api: "ollama",
        timeoutSeconds: 420,
        contextWindow: 131072,
        maxTokens: 16384,
        models: [{ id: "qwen3.5:27b", name: "qwen3.5:27b", input: ["text"] }],
      },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: "ollama-fast/gemma4",
        fallbacks: ["ollama-large/qwen3.5:27b"],
      },
    },
  },
}

OpenClaw가 요청을 보낼 때 active 공급자 접두사는 제거되므로 ollama-large/qwen3.5:27b는 Ollama에 qwen3.5:27b로 도달합니다.

일부 로컬 model은 간단한 prompt에는 답할 수 있지만 전체 agent tool surface에서는 어려움을 겪을 수 있습니다. 전역 runtime 설정을 변경하기 전에 먼저 tool과 context를 제한하는 것부터 시작하세요.

{
  agents: {
    defaults: {
      experimental: {
        localModelLean: true,
      },
      model: { primary: "ollama/gemma4" },
    },
  },
  models: {
    providers: {
      ollama: {
        baseUrl: "http://127.0.0.1:11434",
        apiKey: "ollama-local",
        api: "ollama",
        contextWindow: 32768,
        models: [
          {
            id: "gemma4",
            name: "gemma4",
            input: ["text"],
            params: { num_ctx: 32768 },
            compat: { supportsTools: false },
          },
        ],
      },
    },
  },
}

모델이나 서버가 도구 스키마에서 안정적으로 실패하는 경우에만 compat.supportsTools: false를 사용하세요. 이는 안정성을 위해 에이전트 기능을 줄입니다. localModelLean은 에이전트 표면에서 브라우저, Cron, 메시지 도구를 제거하지만, Ollama의 런타임 컨텍스트나 사고 모드를 변경하지는 않습니다. 반복 실행되거나 숨겨진 추론에 응답 예산을 소비하는 작은 Qwen 스타일 사고 모델에는 명시적인 params.num_ctx 및 params.thinking: false와 함께 사용하세요.

대신 OpenAI 호환 엔드포인트를 사용해야 하는 경우(예: OpenAI 형식만 지원하는 프록시 뒤에서) api: "openai-completions"를 명시적으로 설정하세요.

{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://ollama-host:11434/v1",
        api: "openai-completions",
        injectNumCtxForOpenAICompat: true, // default: true
        apiKey: "ollama-local",
        models: [...]
      }
    }
  }
}

이 모드는 스트리밍과 도구 호출을 동시에 지원하지 않을 수 있습니다. 모델 구성에서 params: { streaming: false }로 스트리밍을 비활성화해야 할 수 있습니다.

Ollama와 함께 api: "openai-completions"를 사용할 때 OpenClaw는 기본적으로 options.num_ctx를 주입하므로 Ollama가 조용히 4096 컨텍스트 윈도로 되돌아가지 않습니다. 프록시/업스트림이 알 수 없는 options 필드를 거부하는 경우 이 동작을 비활성화하세요.

{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://ollama-host:11434/v1",
        api: "openai-completions",
        injectNumCtxForOpenAICompat: false,
        apiKey: "ollama-local",
        models: [...]
      }
    }
  }
}

자동 발견된 모델의 경우, OpenClaw는 사용할 수 있을 때 Ollama가 보고한 컨텍스트 윈도를 사용합니다. 여기에는 사용자 지정 Modelfile의 더 큰 PARAMETER num_ctx 값도 포함됩니다. 그렇지 않으면 OpenClaw가 사용하는 기본 Ollama 컨텍스트 윈도로 대체됩니다.

해당 Ollama 제공자 아래의 모든 모델에 대해 제공자 수준 contextWindow, contextTokens, maxTokens 기본값을 설정한 다음, 필요할 때 모델별로 재정의할 수 있습니다. contextWindow는 OpenClaw의 프롬프트 및 Compaction 예산입니다. 네이티브 Ollama 요청은 params.num_ctx를 명시적으로 구성하지 않는 한 options.num_ctx를 설정하지 않으므로 Ollama는 자체 모델, OLLAMA_CONTEXT_LENGTH 또는 VRAM 기반 기본값을 적용할 수 있습니다. Modelfile을 다시 빌드하지 않고 Ollama의 요청별 런타임 컨텍스트를 제한하거나 강제하려면 params.num_ctx를 설정하세요. 유효하지 않거나, 0이거나, 음수이거나, 유한하지 않은 값은 무시됩니다. OpenAI 호환 Ollama 어댑터는 여전히 구성된 params.num_ctx 또는 contextWindow에서 기본적으로 options.num_ctx를 주입합니다. 업스트림이 options를 거부하는 경우 injectNumCtxForOpenAICompat: false로 이를 비활성화하세요.

네이티브 Ollama 모델 항목은 params 아래에 temperature, top_p, top_k, min_p, num_predict, stop, repeat_penalty, num_batch, num_thread, use_mmap을 포함한 일반적인 Ollama 런타임 옵션도 허용합니다. OpenClaw는 Ollama 요청 키만 전달하므로 streaming 같은 OpenClaw 런타임 params는 Ollama로 누출되지 않습니다. 최상위 Ollama think를 보내려면 params.think 또는 params.thinking을 사용하세요. false는 Qwen 스타일 사고 모델의 API 수준 사고를 비활성화합니다.

{
  models: {
    providers: {
      ollama: {
        contextWindow: 32768,
        models: [
          {
            id: "llama3.3",
            contextWindow: 131072,
            maxTokens: 65536,
            params: {
              num_ctx: 32768,
              temperature: 0.7,
              top_p: 0.9,
              thinking: false,
            },
          }
        ]
      }
    }
  }
}

모델별 agents.defaults.models["ollama/<model>"].params.num_ctx도 작동합니다. 둘 다 구성된 경우 명시적인 제공자 모델 항목이 에이전트 기본값보다 우선합니다.

네이티브 Ollama 모델의 경우 OpenClaw는 Ollama가 기대하는 방식으로 사고 제어를 전달합니다. 즉 options.think가 아니라 최상위 think입니다. /api/show 응답에 thinking 기능이 포함된 자동 발견 모델은 /think low, /think medium, /think high, /think max를 노출합니다. 사고 모델이 아닌 경우 /think off만 노출합니다.

openclaw agent --model ollama/gemma4 --thinking off
openclaw agent --model ollama/gemma4 --thinking low

모델 기본값도 설정할 수 있습니다.

{
  agents: {
    defaults: {
      models: {
        "ollama/gemma4": {
          thinking: "low",
        },
      },
    },
  },
}

모델별 params.think 또는 params.thinking은 특정 구성 모델에 대해 Ollama API 사고를 비활성화하거나 강제할 수 있습니다. 활성 실행에 암시적 기본값 off만 있는 경우 OpenClaw는 이러한 명시적 모델 params를 보존합니다. /think medium 같은 off가 아닌 런타임 명령은 여전히 활성 실행을 재정의합니다.

OpenClaw는 deepseek-r1, reasoning, think 같은 이름의 모델을 기본적으로 추론 가능 모델로 취급합니다.

ollama pull deepseek-r1:32b

추가 구성은 필요하지 않습니다. OpenClaw가 자동으로 표시합니다.

Ollama는 무료이며 로컬에서 실행되므로 모든 모델 비용은 $0으로 설정됩니다. 이는 자동 발견 모델과 수동 정의 모델 모두에 적용됩니다.

번들 Ollama Plugin은 메모리 검색을 위한 메모리 임베딩 제공자를 등록합니다. 구성된 Ollama 기본 URL과 API 키를 사용하고, Ollama의 현재 /api/embed 엔드포인트를 호출하며, 가능할 때 여러 메모리 청크를 하나의 input 요청으로 배치 처리합니다.

쿼리 시점 임베딩은 nomic-embed-text, qwen3-embedding, mxbai-embed-large를 포함하여 접두사가 필요하거나 권장되는 모델에 검색 접두사를 사용합니다. 메모리 문서 배치는 기존 인덱스에 형식 마이그레이션이 필요하지 않도록 원시 상태를 유지합니다.

Ollama를 메모리 검색 임베딩 제공자로 선택하려면:

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "ollama",
        remote: {
          // Default for Ollama. Raise on larger hosts if reindexing is too slow.
          nonBatchConcurrency: 1,
        },
      },
    },
  },
}

원격 임베딩 호스트의 경우 인증을 해당 호스트 범위로 유지하세요.

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "ollama",
        model: "nomic-embed-text",
        remote: {
          baseUrl: "http://gpu-box.local:11434",
          apiKey: "ollama-local",
          nonBatchConcurrency: 2,
        },
      },
    },
  },
}

OpenClaw의 Ollama 통합은 기본적으로 스트리밍과 도구 호출을 동시에 완전히 지원하는 네이티브 Ollama API(/api/chat)를 사용합니다. 특별한 구성이 필요하지 않습니다.

네이티브 /api/chat 요청의 경우 OpenClaw는 사고 제어도 Ollama에 직접 전달합니다. /think off와 openclaw agent --thinking off는 명시적인 모델 params.think/params.thinking 값이 구성되어 있지 않은 한 최상위 think: false를 보내며, /think low|medium|high는 일치하는 최상위 think 노력 문자열을 보냅니다. /think max는 Ollama의 가장 높은 네이티브 노력 수준인 think: "high"에 매핑됩니다.

NVIDIA/CUDA가 있는 WSL2에서 공식 Ollama Linux 설치 프로그램은 Restart=always가 있는 ollama.service systemd 유닛을 만듭니다. 이 서비스가 자동 시작되고 WSL2 부팅 중 GPU 기반 모델을 로드하면, Ollama가 모델을 로드하는 동안 호스트 메모리를 고정할 수 있습니다. Hyper-V 메모리 회수는 이러한 고정 페이지를 항상 회수할 수 없으므로 Windows가 WSL2 VM을 종료하고, systemd가 Ollama를 다시 시작하며, 이 루프가 반복될 수 있습니다.

일반적인 증거:

• Windows 측에서 반복되는 WSL2 재부팅 또는 종료
• WSL2 시작 직후 app.slice 또는 ollama.service의 높은 CPU 사용량
• Linux OOM-killer 이벤트가 아니라 systemd에서 발생한 SIGTERM

OpenClaw는 WSL2, Restart=always로 활성화된 ollama.service, 그리고 표시되는 CUDA 마커를 감지하면 시작 경고를 기록합니다.

완화 방법:

sudo systemctl disable ollama

Windows 측의 %USERPROFILE%\.wslconfig에 다음을 추가한 다음 wsl --shutdown을 실행하세요.

[experimental]
autoMemoryReclaim=disabled

Ollama 서비스 환경에서 더 짧은 keep-alive를 설정하거나, 필요할 때만 Ollama를 수동으로 시작하세요.

export OLLAMA_KEEP_ALIVE=5m
ollama serve

ollama/ollama#11317을 참조하세요.

Ollama가 실행 중이고 OLLAMA_API_KEY(또는 인증 프로필)를 설정했으며, 명시적인 models.providers.ollama 항목을 정의하지 않았는지 확인하세요.

ollama serve

API에 접근할 수 있는지 확인하세요.

curl http://localhost:11434/api/tags

모델이 목록에 없으면 모델을 로컬로 가져오거나 models.providers.ollama에 명시적으로 정의하세요.

ollama list  # See what's installed
ollama pull gemma4
ollama pull gpt-oss:20b
ollama pull llama3.3     # Or another model

Ollama가 올바른 포트에서 실행 중인지 확인하세요.

# Check if Ollama is running
ps aux | grep ollama

# Or restart Ollama
ollama serve

Gateway를 실행하는 동일한 머신과 런타임에서 확인하세요.

openclaw gateway status --deep
curl http://ollama-host:11434/api/tags

일반적인 원인:

• baseUrl이 localhost를 가리키지만 Gateway가 Docker 또는 다른 호스트에서 실행됩니다.
• URL이 /v1을 사용하여 네이티브 Ollama 대신 OpenAI 호환 동작을 선택합니다.
• 원격 호스트에서 Ollama 측 방화벽 또는 LAN 바인딩 변경이 필요합니다.
• 모델이 노트북의 데몬에는 있지만 원격 데몬에는 없습니다.

이는 일반적으로 provider가 OpenAI 호환 모드를 사용 중이거나 모델이 도구 스키마를 처리할 수 없다는 뜻입니다.

네이티브 Ollama 모드를 선호하세요.

{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://ollama-host:11434",
        api: "ollama",
      },
    },
  },
}

작은 로컬 모델이 여전히 도구 스키마에서 실패하면 해당 모델 항목에 compat.supportsTools: false를 설정하고 다시 테스트하세요.

길고 언어적이지 않은 기호 나열로 된 호스팅 Kimi/GLM 응답은 성공적인 어시스턴트 답변이 아니라 실패한 provider 출력으로 처리됩니다. 이렇게 하면 손상된 텍스트를 세션에 유지하지 않고 일반적인 재시도, 폴백 또는 오류 처리가 이어질 수 있습니다.

반복해서 발생하면 원시 모델 이름, 현재 세션 파일, 실행이 Cloud + Local을 사용했는지 Cloud only를 사용했는지 캡처한 다음 새 세션과 폴백 모델을 시도하세요.

openclaw infer model run --model ollama/kimi-k2.5:cloud --prompt "Reply with exactly: ok" --json
openclaw models set ollama/gemma4

큰 로컬 모델은 스트리밍이 시작되기 전에 긴 최초 로드 시간이 필요할 수 있습니다. 시간 초과를 Ollama provider로 제한하고, 선택적으로 Ollama에 턴 사이에 모델을 로드된 상태로 유지하도록 요청하세요.

{
  models: {
    providers: {
      ollama: {
        timeoutSeconds: 300,
        models: [
          {
            id: "gemma4:26b",
            name: "gemma4:26b",
            params: { keep_alive: "15m" },
          },
        ],
      },
    },
  },
}

호스트 자체가 연결을 수락하는 데 느린 경우, timeoutSeconds는 이 provider에 대해 보호되는 Undici 연결 시간 초과도 연장합니다.

많은 Ollama 모델은 하드웨어에서 편안하게 실행할 수 있는 것보다 더 큰 컨텍스트를 표시합니다. 네이티브 Ollama는 params.num_ctx를 설정하지 않는 한 Ollama 자체 런타임 컨텍스트 기본값을 사용합니다. 예측 가능한 첫 토큰 지연 시간을 원할 때는 OpenClaw의 예산과 Ollama의 요청 컨텍스트를 모두 제한하세요.

{
  models: {
    providers: {
      ollama: {
        contextWindow: 32768,
        maxTokens: 8192,
        models: [
          {
            id: "qwen3.5:9b",
            name: "qwen3.5:9b",
            params: { num_ctx: 32768, thinking: false },
          },
        ],
      },
    },
  },
}

OpenClaw가 너무 많은 프롬프트를 보내는 경우 먼저 contextWindow를 낮추세요. Ollama가 머신에 비해 너무 큰 런타임 컨텍스트를 로드하는 경우 params.num_ctx를 낮추세요. 생성이 너무 오래 실행되는 경우 maxTokens를 낮추세요.