Ollama

루프백, 사설 네트워크, .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는 Ollama가 4096토큰 컨텍스트로 조용히 대체하지 않도록 기본적으로 options.num_ctx을 주입합니다. 프록시가 알 수 없는 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 같은 끄기가 아닌 런타임 명령은 여전히 이를 재정의합니다. 명시적으로 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에서 파생된 정확한 호스트 로컬 루프백 오리진으로 보내는 임베딩 요청은 관리형 전달 프록시 대신 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: {          // Ollama의 기본값입니다. 재인덱싱이 너무 느리면 더 큰 호스트에서 늘리십시오.          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  # 설치된 항목 확인ollama pull gemma4ollama pull gpt-oss:20bollama pull llama3.3     # 또는 다른 모델

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 "정확히 다음과 같이 답하십시오: ok" --jsonopenclaw models set ollama/gemma4

대형 로컬 모델은 최초 로드에 오랜 시간이 걸릴 수 있습니다. 시간 초과를 Ollama 제공자로 한정하고, 선택적으로 턴 사이에 모델이 로드된 상태를 유지하십시오.

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

호스트 자체의 연결 수락이 느린 경우 timeoutSeconds를 사용하면 이 제공자의 보호된 연결 시간 초과도 연장됩니다.

많은 모델이 하드웨어에서 원활하게 실행할 수 있는 것보다 큰 컨텍스트를 지원한다고 표시합니다. 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을 낮추십시오.