Ollama

Ollama는 머신에서 오픈소스 모델을 쉽게 실행할 수 있게 해 주는 로컬 LLM 런타임입니다. OpenClaw는 Ollama의 네이티브 API(/api/chat)와 통합되어 스트리밍과 tool calling을 지원하며, OLLAMA_API_KEY(또는 auth profile)를 사용하고 명시적인 models.providers.ollama 항목을 정의하지 않으면 tool-capable 모델을 자동 탐지할 수 있습니다.

원격 Ollama 사용자: OpenClaw와 함께 /v1 OpenAI 호환 URL(http://host:11434/v1)을 사용하지 마세요. 이렇게 하면 tool calling이 깨지고 모델이 원시 tool JSON을 일반 텍스트로 출력할 수 있습니다. 대신 네이티브 Ollama API URL을 사용하세요: baseUrl: "http://host:11434" (/v1 없음).

빠른 시작

Ollama를 설치합니다: https://ollama.ai
모델을 가져옵니다.

ollama pull gpt-oss:20b
# or
ollama pull llama3.3
# or
ollama pull qwen2.5-coder:32b
# or
ollama pull deepseek-r1:32b

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"

Ollama 모델을 사용합니다.

{
  agents: {
    defaults: {
      model: { primary: "ollama/gpt-oss:20b" },
    },
  },
}

Model discovery (implicit 프로바이더)

OLLAMA_API_KEY(또는 auth profile)를 설정하고 models.providers.ollama를 정의하지 않으면, OpenClaw는 http://127.0.0.1:11434의 로컬 Ollama 인스턴스에서 모델을 탐지합니다.

/api/tags와 /api/show를 조회합니다.
tools capability를 보고하는 모델만 유지합니다.
모델이 thinking을 보고하면 reasoning으로 표시합니다.
가능하면 model_info["<arch>.context_length"]에서 contextWindow를 읽습니다.
maxTokens는 context window의 10배로 설정합니다.
모든 비용은 0으로 설정합니다.

이 방식은 수동 모델 등록 없이도 카탈로그를 Ollama의 실제 capability와 맞춰 줍니다. 사용 가능한 모델을 확인하려면:

ollama list
openclaw models list

새 모델을 추가하려면 Ollama로 그냥 pull 하세요.

ollama pull mistral

새 모델은 자동으로 탐지되어 바로 사용할 수 있습니다. models.providers.ollama를 명시적으로 설정하면 자동 탐지는 건너뛰며, 모델을 직접 정의해야 합니다 (아래 참고).

설정

Basic setup (implicit discovery)

Ollama를 활성화하는 가장 단순한 방법은 환경 변수를 쓰는 것입니다.

export OLLAMA_API_KEY="ollama-local"

Explicit setup (manual models)

다음과 같은 경우에는 명시적 설정을 사용하세요.

Ollama가 다른 호스트/포트에서 실행될 때
특정 context window나 모델 목록을 강제하고 싶을 때
tool support를 보고하지 않는 모델도 포함하고 싶을 때

{
  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가 설정되어 있다면 프로바이더 항목에서 apiKey를 생략해도 OpenClaw가 가용성 확인용으로 자동 채웁니다.

Custom base URL (explicit config)

Ollama가 다른 호스트나 포트에서 실행 중이라면(명시적 설정은 auto-discovery를 끄므로 모델을 수동 정의해야 함) 다음과 같이 설정하세요.

{
  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 호환 모드를 사용하므로 tool calling이 안정적이지 않습니다. 경로 접미사 없는 기본 Ollama URL을 사용하세요.

Model selection

구성이 끝나면 모든 Ollama 모델을 사용할 수 있습니다.

{
  agents: {
    defaults: {
      model: {
        primary: "ollama/gpt-oss:20b",
        fallbacks: ["ollama/llama3.3", "ollama/qwen2.5-coder:32b"],
      },
    },
  },
}

Advanced

Reasoning models

OpenClaw는 /api/show에서 Ollama가 thinking을 보고하면 해당 모델을 reasoning-capable로 표시합니다.

ollama pull deepseek-r1:32b

Model Costs

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

Streaming Configuration

OpenClaw의 Ollama 통합은 기본적으로 네이티브 Ollama API(/api/chat)를 사용하며, 스트리밍과 tool calling을 동시에 완전히 지원합니다. 별도 설정은 필요 없습니다.

Legacy OpenAI-Compatible Mode

OpenAI 호환 모드에서는 tool calling이 안정적이지 않습니다. 프록시 때문에 OpenAI 포맷이 꼭 필요하고 네이티브 tool calling 동작에 의존하지 않을 때만 이 모드를 사용하세요.

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: [...]
      }
    }
  }
}

이 모드는 스트리밍과 tool calling을 동시에 지원하지 못할 수 있습니다. 모델 설정의 params: { streaming: false }로 스트리밍을 꺼야 할 수도 있습니다. Ollama에 api: "openai-completions"를 사용할 때 OpenClaw는 기본적으로 options.num_ctx를 주입해 Ollama가 조용히 4096 context window로 되돌아가지 않도록 합니다. 프록시/업스트림이 알 수 없는 options 필드를 거부한다면 이 동작을 끄세요.

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

Context windows

자동 탐지된 모델의 경우 OpenClaw는 가능하면 Ollama가 보고한 context window를 사용하고, 없으면 기본값 8192를 사용합니다. 명시적 프로바이더 설정에서는 contextWindow와 maxTokens를 직접 재정의할 수 있습니다.

Troubleshooting

Ollama not detected

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

ollama serve

API에 접근 가능한지도 확인하세요.

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

No models available

OpenClaw는 tool support를 보고하는 모델만 자동 탐지합니다. 모델이 목록에 없다면 다음 중 하나를 하세요.

tool-capable 모델을 pull 하거나
models.providers.ollama에 모델을 명시적으로 정의하세요.

모델을 추가하려면:

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

Connection refused

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

# Check if Ollama is running
ps aux | grep ollama

# Or restart Ollama
ollama serve

​Ollama

​빠른 시작

​Model discovery (implicit 프로바이더)

​설정

​Basic setup (implicit discovery)

​Explicit setup (manual models)

​Custom base URL (explicit config)

​Model selection

​Advanced

​Reasoning models

​Model Costs

​Streaming Configuration

​Legacy OpenAI-Compatible Mode

​Context windows

​Troubleshooting

​Ollama not detected

​No models available

​Connection refused

​See Also

Ollama

빠른 시작

Model discovery (implicit 프로바이더)

설정

Basic setup (implicit discovery)

Explicit setup (manual models)

Custom base URL (explicit config)

Model selection

Advanced

Reasoning models

Model Costs

Streaming Configuration

Legacy OpenAI-Compatible Mode

Context windows

Troubleshooting

Ollama not detected

No models available

Connection refused

See Also