Ollama

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

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

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

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

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

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

Ollama가 Gateway와 같은 머신에서 실행 중이고 OpenClaw가 설치된 모델을 자동으로 검색하게 하려는 경우 사용하세요.

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

이 경로는 설정을 최소화합니다. 모델을 수동으로 정의하려는 경우가 아니면 models.providers.ollama 블록을 추가하지 마세요.

LAN 호스트에는 기본 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 측 컨텍스트 예산입니다. params.num_ctx는 요청 시 Ollama로 전송됩니다. 하드웨어가 모델의 전체 공지 컨텍스트를 실행할 수 없는 경우 둘을 맞춰 두세요.

로컬 데몬을 실행하지 않고 호스팅 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" },    },  },}

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

ollama signinollama 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 서버가 둘 이상인 경우 사용자 지정 provider ID를 사용하세요. 각 provider에는 자체 호스트, 모델, 인증, 타임아웃, 모델 참조가 있습니다.

{  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가 요청을 보낼 때 활성 provider 접두사는 제거되므로 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, 메시지 도구를 제거하고, 실행에서 직접 메시지 전달 의미를 유지해야 하는 경우를 제외하면 더 큰 카탈로그를 구조화된 Tool Search 컨트롤 뒤에 두도록 기본 설정하지만, 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"를 사용하면 Ollama가 조용히 4096 컨텍스트 창으로 대체하지 않도록 OpenClaw가 기본적으로 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 값을 포함해 Ollama가 보고한 컨텍스트 창을 사용합니다. 그렇지 않으면 OpenClaw가 사용하는 기본 Ollama 컨텍스트 창으로 대체합니다.

해당 Ollama 제공자 아래의 모든 모델에 대해 제공자 수준의 contextWindow, contextTokens, maxTokens 기본값을 설정한 다음, 필요할 때 모델별로 재정의할 수 있습니다. contextWindow는 OpenClaw의 프롬프트 및 Compaction 예산입니다. 명시적으로 params.num_ctx를 구성하지 않는 한 네이티브 Ollama 요청은 options.num_ctx를 설정하지 않으므로, Ollama가 자체 모델, OLLAMA_CONTEXT_LENGTH 또는 VRAM 기반 기본값을 적용할 수 있습니다. Modelfile을 다시 빌드하지 않고 Ollama의 요청별 런타임 컨텍스트를 제한하거나 강제하려면 params.num_ctx를 설정하세요. 유효하지 않거나, 0이거나, 음수이거나, 유한하지 않은 값은 무시됩니다. 이전 구성에서 네이티브 Ollama 요청 컨텍스트를 강제하기 위해 contextWindow 또는 maxTokens만 사용했다면, openclaw doctor --fix를 실행해 해당 명시적 제공자 또는 모델 예산을 params.num_ctx로 복사하세요. 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 런타임 매개변수는 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 offopenclaw agent --model ollama/gemma4 --thinking low

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

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

모델별 params.think 또는 params.thinking은 특정 구성 모델에 대해 Ollama API 사고를 비활성화하거나 강제할 수 있습니다. OpenClaw는 활성 실행에 암시적 기본값 off만 있을 때 이러한 명시적 모델 매개변수를 보존합니다. /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 요청으로 배치 처리합니다.

proxy.enabled=true일 때, 구성된 baseUrl에서 파생된 정확한 host-local loopback origin으로 향하는 Ollama 메모리 임베딩 요청은 관리형 전달 프록시 대신 OpenClaw의 보호된 직접 경로를 사용합니다. 구성된 호스트 이름 자체가 localhost 또는 loopback IP 리터럴이어야 합니다. 단순히 loopback으로 해석되는 DNS 이름은 여전히 관리형 프록시 경로를 사용합니다. LAN, tailnet, 사설 네트워크 및 공개 Ollama 호스트도 관리형 프록시 경로에 남습니다. 다른 호스트나 포트로 리디렉션되면 신뢰를 상속하지 않습니다. 운영자는 여전히 전역 proxy.loopbackMode: "proxy" 설정을 지정해 loopback 트래픽을 프록시를 통해 보내거나, proxy.loopbackMode: "block"을 지정해 연결을 열기 전에 loopback 연결을 거부할 수 있습니다. 이 설정의 프로세스 전체 효과는 관리형 프록시를 참조하세요.

쿼리 시점 임베딩은 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에 직접 전달합니다. 명시적 모델 params.think/params.thinking 값이 구성되어 있지 않다면 /think off와 openclaw agent --thinking off는 최상위 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=5mollama serve

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

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

ollama serve

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

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

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

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

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

# Check if Ollama is runningps aux | grep ollama # Or restart Ollamaollama serve

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

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

일반적인 원인:

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

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

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

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

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

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

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

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

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

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

호스트 자체가 연결 수락이 느린 경우, timeoutSeconds는 이 공급자에 대해 보호된 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를 낮추세요.