Ollama
Ollama는 오픈소스 모델을 로컬에서 쉽게 실행할 수 있는 LLM 런타임입니다. OpenClaw는 Ollama의 네이티브 API(/api/chat)와 통합되며, 스트리밍과 도구 호출을 지원하고, OLLAMA_API_KEY(또는 인증 프로필)를 설정하고 명시적인 models.providers.ollama 항목을 정의하지 않으면 로컬 Ollama 모델을 자동으로 검색할 수 있습니다.
경고: 원격 Ollama 사용자: OpenClaw에서
/v1OpenAI 호환 URL(http://host:11434/v1)을 사용하지 마세요. 도구 호출이 작동하지 않으며, 모델이 도구 JSON을 일반 텍스트로 출력할 수 있습니다. 대신 네이티브 Ollama API URL을 사용하세요:baseUrl: "http://host:11434"(/v1없이).
빠른 시작
온보딩 마법사 (권장)
Ollama를 설정하는 가장 빠른 방법은 온보딩 마법사를 사용하는 것입니다:
openclaw onboard프로바이더 목록에서 Ollama를 선택하세요. 마법사가 다음을 수행합니다:
- Ollama 인스턴스에 접근할 수 있는 Ollama 기본 URL을 요청합니다 (기본값
http://127.0.0.1:11434). - Cloud + Local (클라우드 모델과 로컬 모델) 또는 Local (로컬 모델만) 중 선택할 수 있습니다.
- Cloud + Local을 선택하고 ollama.com에 로그인하지 않은 경우 브라우저 로그인 흐름을 엽니다.
- 사용 가능한 모델을 검색하고 기본값을 추천합니다.
- 선택한 모델이 로컬에 없으면 자동으로 풀(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수동 설정
-
Ollama 설치: https://ollama.com/download
-
로컬 추론을 원하면 로컬 모델을 풀합니다:
ollama pull glm-4.7-flash
# 또는
ollama pull gpt-oss:20b
# 또는
ollama pull llama3.3- 클라우드 모델도 사용하려면 로그인합니다:
ollama signin- 온보딩을 실행하고
Ollama를 선택합니다:
openclaw onboardLocal: 로컬 모델만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
- 수동 설정을 선호한다면 OpenClaw에서 Ollama를 직접 활성화합니다 (어떤 값이든 가능합니다; Ollama는 실제 키를 요구하지 않습니다):
# 환경 변수 설정
export OLLAMA_API_KEY="ollama-local"
# 또는 설정 파일에서 구성
openclaw config set models.providers.ollama.apiKey "ollama-local"- 모델을 확인하거나 전환합니다:
openclaw models list
openclaw models set ollama/glm-4.7-flash- 또는 설정에서 기본값을 지정합니다:
{
agents: {
defaults: {
model: { primary: "ollama/glm-4.7-flash" },
},
},
}모델 자동 검색 (암시적 프로바이더)
OLLAMA_API_KEY(또는 인증 프로필)를 설정하고 models.providers.ollama를 정의하지 않으면, OpenClaw가 http://127.0.0.1:11434의 로컬 Ollama 인스턴스에서 모델을 자동으로 검색합니다:
/api/tags를 쿼리합니다/api/show조회를 통해 가능한 경우contextWindow을 읽습니다- 모델명 휴리스틱(
r1,reasoning,think)으로reasoning을 표시합니다 maxTokens를 OpenClaw에서 사용하는 기본 Ollama 최대 토큰 값으로 설정합니다- 모든 비용을
0으로 설정합니다
이를 통해 로컬 Ollama 인스턴스와 카탈로그를 동기화하면서 수동 모델 항목을 생략할 수 있습니다.
사용 가능한 모델을 확인하려면:
ollama list
openclaw models list새 모델을 추가하려면 Ollama로 풀하면 됩니다:
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가 설정되어 있으면 프로바이더 항목에서 apiKey를 생략할 수 있으며, OpenClaw가 가용성 검사 시 자동으로 채워줍니다.
커스텀 기본 URL (명시적 설정)
Ollama가 다른 호스트나 포트에서 실행 중인 경우 (명시적 설정은 자동 검색을 비활성화하므로 모델을 수동으로 정의해야 합니다):
{
models: {
providers: {
ollama: {
apiKey: "ollama-local",
baseUrl: "http://ollama-host:11434", // /v1 없이 - 네이티브 Ollama API URL 사용
api: "ollama", // 네이티브 도구 호출 동작을 보장하기 위해 명시적으로 설정
},
},
},
}경고: 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는 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, // 기본값: 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 컨텍스트 윈도우로 대체합니다. 명시적 프로바이더 설정에서 contextWindow과 maxTokens를 재정의할 수 있습니다.
문제 해결
Ollama가 감지되지 않음
Ollama가 실행 중이고 OLLAMA_API_KEY(또는 인증 프로필)가 설정되어 있으며, 명시적인 models.providers.ollama 항목을 정의하지 않았는지 확인하세요:
ollama serveAPI에 접근 가능한지 확인합니다:
curl http://localhost:11434/api/tags사용 가능한 모델이 없음
모델이 목록에 없다면 다음 중 하나를 수행하세요:
- 모델을 로컬에 풀하거나,
models.providers.ollama에 모델을 명시적으로 정의합니다.
모델을 추가하려면:
ollama list # 설치된 모델 확인
ollama pull glm-4.7-flash
ollama pull gpt-oss:20b
ollama pull llama3.3 # 또는 다른 모델연결 거부
Ollama가 올바른 포트에서 실행 중인지 확인합니다:
# Ollama 실행 중인지 확인
ps aux | grep ollama
# 또는 Ollama 재시작
ollama serve