메인 콘텐츠로 건너뛰기

​
Ollama

Ollama는 오픈 소스 모델을 자신의 머신에서 쉽게 실행할 수 있게 해주는 로컬 LLM 런타임입니다. OpenClaw는 Ollama의 네이티브 API(api/chat)와 통합되며, 스트리밍과 도구 호출을 지원하고, OLLAMA_API_KEY(또는 인증 프로필)를 사용하도록 선택했으며 명시적인 models.providers.ollama 항목을 정의하지 않은 경우 로컬 Ollama 모델을 자동 검색할 수 있습니다.
원격 Ollama 사용자: OpenClaw와 함께 /v1 OpenAI 호환 URL(http://host:11434/v1)을 사용하지 마세요. 이렇게 하면 도구 호출이 깨질 수 있고, 모델이 원시 도구 JSON을 일반 텍스트로 출력할 수 있습니다. 대신 네이티브 Ollama API URL을 사용하세요: baseUrl: "http://host:11434" (/v1 없음).

​
빠른 시작

​
온보딩(권장)

Ollama를 설정하는 가장 빠른 방법은 온보딩을 이용하는 것입니다. 
openclaw onboard
provider 목록에서 Ollama를 선택하세요. 온보딩은 다음을 수행합니다.
  1. 인스턴스에 접근할 수 있는 Ollama 기본 URL을 묻습니다(기본값 http://127.0.0.1:11434).
  2. Cloud + Local(클라우드 모델과 로컬 모델) 또는 Local(로컬 모델만)을 선택하게 합니다.
  3. Cloud + Local을 선택했고 ollama.com에 로그인되어 있지 않으면 브라우저 로그인 흐름을 엽니다.
  4. 사용 가능한 모델을 검색하고 기본값을 제안합니다.
  5. 선택한 모델을 로컬에서 사용할 수 없으면 자동으로 pull합니다.
비대화형 모드도 지원됩니다. 
openclaw onboard --non-interactive \
  --auth-choice ollama \
  --accept-risk
선택적으로 사용자 지정 기본 URL이나 모델을 지정할 수도 있습니다. 
openclaw onboard --non-interactive \
  --auth-choice ollama \
  --custom-base-url "http://ollama-host:11434" \
  --custom-model-id "qwen3.5:27b" \
  --accept-risk

​
수동 설정

  1. Ollama를 설치합니다: https://ollama.com/download
  2. 로컬 추론을 원한다면 로컬 모델을 pull합니다. 
ollama pull glm-4.7-flash
# or
ollama pull gpt-oss:20b
# or
ollama pull llama3.3
  1. 클라우드 모델도 원한다면 로그인합니다.
ollama signin
  1. 온보딩을 실행하고 Ollama를 선택합니다.
openclaw onboard
  • Local: 로컬 모델만
  • Cloud + Local: 로컬 모델과 클라우드 모델
  • kimi-k2.5:cloud, minimax-m2.5:cloud, glm-5:cloud와 같은 클라우드 모델은 로컬 ollama pull이 필요하지 않습니다
현재 OpenClaw가 제안하는 값은 다음과 같습니다.
  • 로컬 기본값: glm-4.7-flash
  • 클라우드 기본값: kimi-k2.5:cloud, minimax-m2.5:cloud, glm-5:cloud
  1. 수동 설정을 선호한다면 OpenClaw에서 Ollama를 직접 활성화하세요(아무 값이나 작동하며, Ollama에는 실제 키가 필요하지 않습니다).
# Set environment variable
export OLLAMA_API_KEY="ollama-local"

# Or configure in your config file
openclaw config set models.providers.ollama.apiKey "ollama-local"
  1. 모델을 확인하거나 전환합니다.
openclaw models list
openclaw models set ollama/glm-4.7-flash
  1. 또는 설정에서 기본값을 지정합니다.
{
  agents: {
    defaults: {
      model: { primary: "ollama/glm-4.7-flash" },
    },
  },
}

​
모델 검색(암시적 provider)

OLLAMA_API_KEY(또는 인증 프로필)를 설정하고 models.providers.ollama를 정의하지 않으면, OpenClaw는 http://127.0.0.1:11434의 로컬 Ollama 인스턴스에서 모델을 검색합니다.
  • /api/tags를 조회합니다
  • 가능할 경우 contextWindow를 읽기 위해 최선의 노력으로 /api/show 조회를 사용합니다
  • 모델 이름 휴리스틱(r1, reasoning, think)으로 reasoning을 표시합니다
  • maxTokens는 OpenClaw가 사용하는 기본 Ollama 최대 토큰 상한으로 설정합니다
  • 모든 비용을 0으로 설정합니다
이렇게 하면 수동 모델 항목 없이도 카탈로그를 로컬 Ollama 인스턴스와 일치시킬 수 있습니다. 사용 가능한 모델을 보려면 다음을 실행하세요. 
ollama list
openclaw models list
새 모델을 추가하려면 Ollama로 pull하기만 하면 됩니다. 
ollama pull mistral
새 모델은 자동으로 검색되어 사용할 수 있게 됩니다. models.providers.ollama를 명시적으로 설정하면 자동 검색은 건너뛰어지며 모델을 수동으로 정의해야 합니다(아래 참고).

​
구성

​
기본 설정(암시적 검색)

Ollama를 활성화하는 가장 간단한 방법은 환경 변수를 사용하는 것입니다. 
export OLLAMA_API_KEY="ollama-local"

​
명시적 설정(수동 모델)

다음과 같은 경우에는 명시적 구성을 사용하세요.
  • Ollama가 다른 호스트/포트에서 실행되는 경우
  • 특정 컨텍스트 윈도우나 모델 목록을 강제하고 싶은 경우
  • 완전히 수동으로 모델을 정의하고 싶은 경우
{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://ollama-host:11434",
        apiKey: "ollama-local",
        api: "ollama",
        models: [
          {
            id: "gpt-oss:20b",
            name: "GPT-OSS 20B",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 8192,
            maxTokens: 8192 * 10
          }
        ]
      }
    }
  }
}
OLLAMA_API_KEY가 설정되어 있으면 provider 항목에서 apiKey를 생략해도 되며, OpenClaw가 가용성 확인을 위해 이를 채웁니다.

​
사용자 지정 기본 URL(명시적 구성)

Ollama가 다른 호스트나 포트에서 실행되는 경우(명시적 구성을 사용하면 자동 검색이 비활성화되므로 모델을 수동으로 정의하세요): 
{
  models: {
    providers: {
      ollama: {
        apiKey: "ollama-local",
        baseUrl: "http://ollama-host:11434", // No /v1 - use native Ollama API URL
        api: "ollama", // Set explicitly to guarantee native tool-calling behavior
      },
    },
  },
}
URL에 /v1을 추가하지 마세요. /v1 경로는 OpenAI 호환 모드를 사용하며, 이 모드에서는 도구 호출이 안정적이지 않습니다. 경로 접미사 없이 기본 Ollama URL을 사용하세요.

​
모델 선택

구성이 완료되면 모든 Ollama 모델을 사용할 수 있습니다. 
{
  agents: {
    defaults: {
      model: {
        primary: "ollama/gpt-oss:20b",
        fallbacks: ["ollama/llama3.3", "ollama/qwen2.5-coder:32b"],
      },
    },
  },
}

​
클라우드 모델

클라우드 모델을 사용하면 로컬 모델과 함께 클라우드에서 호스팅되는 모델(예: kimi-k2.5:cloud, minimax-m2.5:cloud, glm-5:cloud)을 실행할 수 있습니다. 클라우드 모델을 사용하려면 설정 중 Cloud + Local 모드를 선택하세요. 마법사는 로그인 상태를 확인하고 필요할 때 브라우저 로그인 흐름을 엽니다. 인증을 확인할 수 없으면 마법사는 로컬 모델 기본값으로 대체합니다. ollama.com/signin에서 직접 로그인할 수도 있습니다. OpenClaw는 번들된 web_search provider로 Ollama Web Search도 지원합니다.
  • 구성된 Ollama 호스트를 사용합니다(models.providers.ollama.baseUrl이 설정되어 있으면 그 값을, 그렇지 않으면 http://127.0.0.1:11434를 사용).
  • 키가 필요하지 않습니다.
  • Ollama가 실행 중이고 ollama signin으로 로그인되어 있어야 합니다.
openclaw onboard 또는 openclaw configure --section web 중에 Ollama Web Search를 선택하거나, 다음과 같이 설정하세요. 
{
  tools: {
    web: {
      search: {
        provider: "ollama",
      },
    },
  },
}
전체 설정 및 동작 세부 사항은 Ollama Web Search를 참조하세요.

​
고급

​
추론 모델

OpenClaw는 deepseek-r1, reasoning, think와 같은 이름이 포함된 모델을 기본적으로 추론 가능 모델로 취급합니다. 
ollama pull deepseek-r1:32b

​
모델 비용

Ollama는 무료이며 로컬에서 실행되므로, 모든 모델 비용은 $0으로 설정됩니다.

​
스트리밍 구성

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

​
레거시 OpenAI 호환 모드

OpenAI 호환 모드에서는 도구 호출이 안정적이지 않습니다. 프록시 때문에 OpenAI 형식이 필요하고 네이티브 도구 호출 동작에 의존하지 않는 경우에만 이 모드를 사용하세요.
대신 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는 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는 가능하면 Ollama가 보고한 컨텍스트 윈도우를 사용하고, 그렇지 않으면 OpenClaw가 사용하는 기본 Ollama 컨텍스트 윈도우로 대체합니다. 명시적 provider 구성에서 contextWindow와 maxTokens를 재정의할 수 있습니다.

​
문제 해결

​
Ollama가 감지되지 않음

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 installed
ollama pull glm-4.7-flash
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

​
함께 보기