Ollama Cloud Provider
기준일: 2026-07-26
난이도: 중급
공식 기준: Ollama Cloud
개요
이 페이지는 OpenClaw Ollama Cloud provider의 인증, 모델 ref, 온보딩 플래그, 설정 키를 공식 문서 기준으로 정리합니다.
공식 요약: Use Ollama Cloud directly with OpenClaw
model ref는 보통 provider/model 형식입니다. API key·endpoint·model id는 아래 원문 값을 그대로 쓰세요. 임의로 키나 엔드포인트를 만들지 마세요.
공식 문서 기반 상세
아래는 공식 providers/ollama-cloud 문서를 Mintlify 컴포넌트만 정리하고 공통 제목을 한국어로 맞춘 내용입니다. 설정 키, env, model ref, CLI 플래그는 원문 그대로 유지합니다.
Ollama Cloud is Ollama's hosted model API. The ollama-cloud provider calls it
directly at https://ollama.com over Ollama's native /api/chat API, with no
local Ollama server and no local Ollama app signed into cloud mode. Use model
refs like ollama-cloud/kimi-k2.6.
OpenClaw registers ollama-cloud as its own provider id so cloud-only
credentials, live catalog discovery, and model selection do not get mixed with
a local ollama host. For local Ollama, hybrid cloud-plus-local routing,
embeddings, and custom host details, see Ollama.
설정
Create an Ollama Cloud API key at ollama.com/settings/keys, then run:
openclaw onboard --auth-choice ollama-cloud
Or set:
export OLLAMA_API_KEY="<your-ollama-cloud-api-key>" # pragma: allowlist secret
Non-interactive onboarding accepts the key directly:
openclaw onboard --auth-choice ollama-cloud --ollama-cloud-api-key "<key>"
Onboarding sets the default model to ollama-cloud/kimi-k2.5:cloud.
기본값
- Provider:
ollama-cloud - Base URL:
https://ollama.com - Env var:
OLLAMA_API_KEY - API style: Ollama native
/api/chat - Onboarding default model:
ollama-cloud/kimi-k2.5:cloud
When to choose Ollama Cloud
- You want hosted Ollama models without running
ollama servelocally. - You want the same native Ollama chat API shape OpenClaw uses for local
Ollama, but pointed at
https://ollama.com. - You want a simple cloud path for models that are already in Ollama's hosted catalog.
- You do not need local model pulls, local GPU control, or LAN-only inference.
Use Ollama instead when you want local-only or
cloud-plus-local routing through a signed-in Ollama host. Use an
OpenAI-compatible provider instead when you need /v1/chat/completions
semantics or provider-specific OpenAI-style features.
모델
The provider requires an API key; without one it stays inactive. With a key, OpenClaw discovers Ollama Cloud models live from the hosted catalog:
openclaw models list --provider ollama-cloud
openclaw models set ollama-cloud/kimi-k2.6
Hosted ids in the live catalog include deepseek-v4-flash, glm-5,
gpt-oss:20b, kimi-k2.6, and minimax-m2.7. When live discovery returns
nothing, OpenClaw falls back to the bundled rows kimi-k2.5:cloud,
minimax-m2.7:cloud, glm-5.1:cloud, and glm-5.2:cloud.
Model ids are cloud catalog ids, not local pull names. If a model name works in
a local Ollama host but is absent from the hosted catalog, use the ollama
provider with that local host instead.
Live test
For Ollama Cloud API-key smoke tests, point the Ollama live test at the hosted endpoint and choose a model from your current catalog:
export OLLAMA_API_KEY="<your-ollama-cloud-api-key>" # pragma: allowlist secret
OPENCLAW_LIVE_TEST=1 \
OPENCLAW_LIVE_OLLAMA=1 \
OPENCLAW_LIVE_OLLAMA_BASE_URL=https://ollama.com \
OPENCLAW_LIVE_OLLAMA_MODEL=kimi-k2.6 \
pnpm test:live -- extensions/ollama/ollama.live.test.ts
The cloud smoke runs text, native stream, and web search; set
OPENCLAW_LIVE_OLLAMA_WEB_SEARCH=0 to skip web search. It skips embeddings by
default for https://ollama.com because Ollama Cloud API keys may not
authorize /api/embed; force them with OPENCLAW_LIVE_OLLAMA_EMBEDDINGS=1.
문제 해결
Ollama Cloud requires an API key/Set OLLAMA_API_KEYerrors: provide a real cloud API key. The localollama-localmarker is only for local or private Ollama hosts.- Unknown model errors: run
openclaw models list --provider ollama-cloudand copy the hosted model id exactly. - Tool-call or raw JSON issues on custom Ollama hosts: check whether you are
accidentally using an OpenAI-compatible
/v1URL. Ollama routes should use the native base URL with no/v1suffix.
관련 문서
검증 체크리스트
-
openclaw models list --provider ollama-cloud로 모델이 보이는지 확인 - 기본 model alias를
agents.defaults.model.primary에 설정했는지 확인 - API key / OAuth / 로컬 런타임 인증 경로를 공식 문서와 대조했는지 확인
- failover 시 데이터가 다른 provider로 이동할 수 있는지 검토