Ollama

local loopback, 사설 네트워크, .local, 호스트 이름만 있는 Ollama URL에는 실제 베어러 토큰이 필요하지 않습니다. OpenClaw은 이러한 URL에 ollama-local 마커를 사용합니다.

공개 원격 호스트와 https://ollama.com에는 실제 자격 증명이 필요합니다. OLLAMA_API_KEY, 인증 프로필 또는 제공자의 apiKey를 사용하세요. 호스팅 서비스를 직접 사용할 때는 ollama-cloud 제공자를 권장합니다.

api: "ollama"를 사용하는 사용자 지정 제공자에도 동일한 규칙이 적용됩니다. 예를 들어 사설 LAN 호스트를 가리키는 ollama-remote 제공자는 apiKey: "ollama-local"을 사용할 수 있습니다. 하위 에이전트는 이를 누락된 자격 증명으로 처리하지 않고 Ollama 제공자 훅을 통해 해당 마커를 해석합니다. 임베딩이 해당 Ollama 엔드포인트를 사용하도록 agents.defaults.memorySearch.provider가 사용자 지정 제공자 ID를 가리키게 할 수도 있습니다.

auth-profiles.json은 제공자 ID의 자격 증명을 저장합니다. 엔드포인트 설정(baseUrl, api, 모델, 헤더, 제한 시간)은 models.providers.<id>에 넣으세요. { "ollama-windows": { "apiKey": "ollama-local" } } 같은 이전 평면 파일은 런타임 형식이 아닙니다. openclaw doctor --fix는 백업을 만든 뒤 이를 표준 ollama-windows:default API 키 프로필로 다시 작성합니다. 해당 레거시 파일의 baseUrl 값은 불필요한 정보이므로 제공자 구성으로 옮겨야 합니다.

Ollama 메모리 임베딩의 베어러 인증은 선언된 호스트로 범위가 제한됩니다.

• 제공자 수준 키는 해당 제공자의 호스트에만 전송됩니다.
• agents.*.memorySearch.remote.apiKey는 해당 원격 임베딩 호스트에만 전송됩니다.
• OLLAMA_API_KEY 환경 변수 값만 설정된 경우 Ollama Cloud 규칙으로 취급되며, 기본적으로 로컬/자체 호스팅 호스트에는 전송되지 않습니다.

Gateway와 같은 머신에서 실행되며 자동으로 검색되는 Ollama:

ollama serveollama pull gemma4export OLLAMA_API_KEY="ollama-local"openclaw models list --provider ollamaopenclaw models set ollama/gemma4

수동 모델이 필요하지 않다면 models.providers.ollama 블록을 추가하지 마세요.

{  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의 컨텍스트 예산이며, params.num_ctx는 Ollama로 전송됩니다. 하드웨어에서 모델이 알리는 전체 컨텍스트를 실행할 수 없는 경우 두 값을 일치시킵니다.

로컬 데몬 없이 호스팅 모델을 직접 사용합니다.

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" },    },  },}

이 구성 대신 전용 ollama-cloud 공급자 ID를 사용하려면 Ollama Cloud를 참조하세요.

둘 이상의 Ollama 서버를 실행할 때는 사용자 지정 공급자 ID를 사용합니다. 각 서버는 자체 호스트, 모델, 인증, 제한 시간을 가집니다.

{  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는 Ollama를 호출하기 전에 활성 공급자 접두사를 제거하며, 활성 공급자 접두사가 없으면 기본 ollama/ 접두사를 제거합니다. 따라서 ollama-large/qwen3.5:27b는 Ollama에 qwen3.5:27b로 전달됩니다.

일부 로컬 모델은 간단한 프롬프트는 처리하지만 전체 에이전트 도구 표면에서는 어려움을 겪습니다. 전역 런타임 설정을 변경하기 전에 도구와 컨텍스트를 제한하세요.

{  agents: {    list: [      {        id: "local",        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, 메시지, 미디어 생성, 음성, PDF 도구를 직접 에이전트 표면에서 제거하고, 더 큰 카탈로그를 도구 검색 뒤에 배치합니다. 이 설정은 Ollama의 런타임 컨텍스트나 사고 모드를 변경하지 않습니다. 반복에 빠지거나 숨겨진 추론에 토큰 예산을 소모하는 소형 Qwen 계열 사고 모델에는 params.num_ctx 및 params.thinking: false와 함께 사용하세요.

/v1/chat/completions 뒤의 프록시에는 api: "openai-completions"를 명시적으로 설정하세요.

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

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

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는 사용자 지정 Modelfile의 더 큰 PARAMETER num_ctx 값을 포함하여 /api/show가 보고하는 컨텍스트 창을 사용합니다. 보고되지 않으면 OpenClaw의 기본 Ollama 컨텍스트 창을 사용합니다.

공급자 수준의 contextWindow, contextTokens, maxTokens는 해당 공급자의 모든 모델에 기본값을 설정하며 모델별로 재정의할 수 있습니다. contextWindow는 OpenClaw 자체의 프롬프트/Compaction 예산입니다. 네이티브 /api/chat 요청은 params.num_ctx를 명시적으로 설정하지 않는 한 options.num_ctx를 설정하지 않으므로, Ollama는 자체 모델, OLLAMA_CONTEXT_LENGTH 또는 VRAM 기반 기본값을 적용합니다. 유효하지 않거나 0, 음수 또는 유한하지 않은 params.num_ctx 값은 무시됩니다. 이전 구성이 네이티브 요청 컨텍스트를 강제하기 위해 contextWindow/maxTokens만 사용했다면 openclaw doctor --fix를 실행하여 해당 값을 params.num_ctx로 복사하세요. OpenAI 호환 어댑터는 여전히 구성된 params.num_ctx 또는 contextWindow에서 기본적으로 options.num_ctx를 주입합니다. 업스트림이 options를 거부하면 injectNumCtxForOpenAICompat: false로 비활성화하세요.

네이티브 모델 항목은 params 아래에서 일반적인 Ollama 런타임 옵션도 허용하며, 네이티브 /api/chat의 options로 전달합니다: num_keep, seed, num_predict, top_k, top_p, min_p, typical_p, repeat_last_n, temperature, repeat_penalty, presence_penalty, frequency_penalty, stop, num_batch, num_gpu, main_gpu, use_mmap, num_thread. 일부 키(format, keep_alive, truncate, shift)는 중첩된 options 대신 최상위 요청 필드로 전달됩니다. OpenClaw는 이러한 Ollama 요청 키만 전달하므로 streaming과 같은 런타임 전용 매개변수는 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도 작동합니다. 둘 다 설정된 경우 명시적인 공급자 모델 항목이 우선합니다.

OpenClaw는 Ollama가 예상하는 방식대로 사고 설정을 전달합니다. options.think가 아니라 최상위 think를 사용합니다. /api/show가 thinking 기능을 보고하는 자동 검색 모델은 /think low, /think medium, /think high, /think max를 제공하며, 사고 모델이 아닌 경우 /think off만 제공합니다.

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

또는 모델 기본값을 설정하세요.

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

모델별 params.think/params.thinking 설정으로 특정 모델의 API 사고를 비활성화하거나 강제할 수 있습니다. 활성 실행에 암시적 기본값인 off만 적용된 경우 OpenClaw는 해당 명시적 설정을 유지합니다. 단, /think medium 같은 off가 아닌 런타임 명령은 여전히 이를 재정의합니다. reasoning: false로 명시된 모델에는 참으로 평가되는 사고 요청을 절대 전송하지 않으며, think: false 요청은 항상 전송합니다.

이름이 deepseek-r1, reasoning, reason 또는 think인 모델은 기본적으로 추론 가능 모델로 취급되므로 추가 설정이 필요하지 않습니다.

ollama pull deepseek-r1:32b

Ollama는 로컬에서 무료로 실행되므로 자동 검색된 모델과 수동으로 정의한 모델 모두의 모델 비용은 0입니다.

번들 Ollama Plugin은 메모리 검색을 위한 메모리 임베딩 제공자를 등록합니다. 설정된 Ollama 기본 URL과 API 키를 사용하고 /api/embed를 호출하며, 가능한 경우 여러 메모리 청크를 하나의 input 요청으로 일괄 처리합니다.

proxy.enabled=true이면 설정된 baseUrl에서 파생된 정확한 호스트 로컬 local loopback 오리진으로 보내는 임베딩 요청은 관리형 정방향 프록시 대신 OpenClaw의 보호된 직접 경로를 사용합니다. 설정된 호스트 이름 자체가 localhost 또는 루프백 IP 리터럴이어야 합니다. 단순히 루프백으로 확인되는 DNS 이름은 여전히 관리형 프록시 경로를 사용합니다. LAN, tailnet, 사설 네트워크 및 공개 Ollama 호스트는 항상 관리형 프록시 경로를 유지하며, 다른 호스트나 포트로의 리디렉션에는 신뢰가 승계되지 않습니다. proxy.loopbackMode: "proxy"는 루프백 트래픽도 프록시를 통해 라우팅하고, proxy.loopbackMode: "block"은 연결 전에 이를 거부합니다. 관리형 프록시를 참조하세요.

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

{  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,        },      },    },  },}

Ollama는 기본적으로 스트리밍과 도구 호출을 함께 지원하는 네이티브 API (/api/chat)를 사용하므로 별도 설정이 필요하지 않습니다.

네이티브 요청에서는 사고 제어가 직접 전달됩니다. 명시적인 params.think/params.thinking이 설정되지 않은 경우 /think off와 openclaw agent --thinking off는 최상위 think: false를 전송합니다. /think low|medium|high는 일치하는 노력 수준 문자열을 전송하고, /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를 재시작하면서 이 과정이 반복될 수 있습니다.

징후: WSL2의 반복적인 재부팅 또는 종료, WSL2 시작 직후 app.slice나 ollama.service의 높은 CPU 사용량, Linux OOM 종료 프로세스가 아닌 systemd에서 발생한 SIGTERM.

OpenClaw는 WSL2, Restart=always가 설정되고 활성화된 ollama.service, 표시되는 CUDA 표식을 감지하면 시작 경고를 기록합니다.

완화 방법:

sudo systemctl disable ollama

Windows 측에서는 %USERPROFILE%\.wslconfig에 다음 내용을 추가한 후 wsl --shutdown을 실행하세요.

[experimental]autoMemoryReclaim=disabled

또는 연결 유지 시간을 단축하거나 필요한 경우에만 Ollama를 수동으로 시작하세요.

export OLLAMA_KEEP_ALIVE=5mollama serve

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

Ollama가 실행 중이고 OLLAMA_API_KEY 또는 인증 프로필이 설정되어 있으며, models.providers.ollama가 명시적으로 정의되어 있지 않은지 확인하세요.

ollama servecurl http://localhost:11434/api/tags

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

ollama list  # See what's installedollama pull gemma4ollama pull gpt-oss:20bollama pull llama3.3     # Or another model

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

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

일반적인 원인:

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

일반적으로 제공자가 OpenAI 호환 모드에 있거나 모델이 도구 스키마를 처리하지 못하는 경우입니다. 네이티브 모드를 권장합니다.

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

소형 로컬 모델이 여전히 도구 스키마를 처리하지 못하면 해당 모델 항목에 compat.supportsTools: false를 설정하고 다시 테스트하세요.

호스팅된 Kimi/GLM 응답이 길고 언어적 의미가 없는 기호의 연속으로 구성된 경우, 성공적인 응답이 아니라 제공자 호출 실패로 처리됩니다. 따라서 손상된 텍스트를 세션에 저장하는 대신 일반적인 재시도, 대체 경로 및 오류 처리가 수행됩니다.

문제가 반복되면 모델 이름, 현재 세션 파일, 실행에서 Cloud + Local 또는 Cloud only를 사용했는지 기록한 후 새 세션과 대체 모델을 시도하세요.

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

대형 로컬 모델은 최초 로드에 오랜 시간이 필요할 수 있습니다. 시간 초과를 Ollama 제공자로 한정하고 선택적으로 전환 사이에도 모델을 로드된 상태로 유지하세요.

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

호스트 자체가 연결을 느리게 수락하는 경우 timeoutSeconds는 이 제공자의 보호된 연결 시간 초과도 연장합니다.

많은 모델이 하드웨어에서 원활하게 실행할 수 있는 크기보다 더 큰 컨텍스트를 지원한다고 표시합니다. 네이티브 Ollama는 params.num_ctx가 설정되지 않으면 자체 런타임 기본값을 사용합니다. 예측 가능한 첫 토큰 지연 시간을 위해 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를 낮추세요.