Ollama

Ollama là một runtime LLM cục bộ giúp các bạn dễ dàng chạy các model mã nguồn mở trên máy tính của mình. OpenClaw tích hợp với API tương thích OpenAI của Ollama và có thể tự động phát hiện các model hỗ trợ tool khi các bạn bật bằng OLLAMA_API_KEY (hoặc auth profile) và không định nghĩa rõ ràng entry models.providers.ollama.

Bắt đầu nhanh

  1. Cài đặt Ollama: https://ollama.ai

  2. Pull một model:

ollama pull llama3.3
# hoặc
ollama pull qwen2.5-coder:32b
# hoặc
ollama pull deepseek-r1:32b
  1. Bật Ollama cho OpenClaw (giá trị nào cũng được; Ollama không cần key thật):
# Set biến môi trường
export OLLAMA_API_KEY="ollama-local"

# Hoặc cấu hình trong config file
openclaw config set models.providers.ollama.apiKey "ollama-local"
  1. Sử dụng các model Ollama:
{
  agents: {
    defaults: {
      model: { primary: "ollama/llama3.3" },
    },
  },
}

Tự động phát hiện model (implicit provider)

Khi các bạn set OLLAMA_API_KEY (hoặc auth profile) và không định nghĩa models.providers.ollama, OpenClaw sẽ tự động phát hiện các model từ Ollama instance cục bộ tại http://127.0.0.1:11434:

  • Query /api/tags và /api/show
  • Chỉ giữ lại các model báo cáo có khả năng tools
  • Đánh dấu reasoning khi model báo cáo thinking
  • Đọc contextWindow từ model_info["<arch>.context_length"] khi có sẵn
  • Set maxTokens bằng 10× context window
  • Set tất cả chi phí về 0

Cách này giúp tránh phải nhập model thủ công trong khi vẫn giữ catalog đồng bộ với khả năng của Ollama.

Để xem các model có sẵn:

ollama list
openclaw models list

Để thêm model mới, chỉ cần pull nó bằng Ollama:

ollama pull mistral

Model mới sẽ tự động được phát hiện và sẵn sàng sử dụng.

Nếu các bạn set models.providers.ollama một cách rõ ràng, tính năng tự động phát hiện sẽ bị bỏ qua và các bạn phải định nghĩa model thủ công (xem bên dưới).

Cấu hình

Cài đặt cơ bản (tự động phát hiện)

Cách đơn giản nhất để bật Ollama là qua biến môi trường:

export OLLAMA_API_KEY="ollama-local"

Cài đặt rõ ràng (model thủ công)

Dùng config rõ ràng khi:

  • Ollama chạy trên host/port khác.
  • Các bạn muốn force context window hoặc danh sách model cụ thể.
  • Các bạn muốn bao gồm các model không báo cáo hỗ trợ tool.
{
  models: {
    providers: {
      ollama: {
        // Dùng host có chứa /v1 cho API tương thích OpenAI
        baseUrl: "http://ollama-host:11434/v1",
        apiKey: "ollama-local",
        api: "openai-completions",
        models: [
          {
            id: "llama3.3",
            name: "Llama 3.3",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 8192,
            maxTokens: 8192 * 10
          }
        ]
      }
    }
  }
}

Nếu OLLAMA_API_KEY đã được set, các bạn có thể bỏ qua apiKey trong provider entry và OpenClaw sẽ tự điền nó cho việc kiểm tra khả dụng.

Custom base URL (config rõ ràng)

Nếu Ollama chạy trên host hoặc port khác (config rõ ràng sẽ tắt tự động phát hiện, nên phải định nghĩa model thủ công):

{
  models: {
    providers: {
      ollama: {
        apiKey: "ollama-local",
        baseUrl: "http://ollama-host:11434/v1",
      },
    },
  },
}

Chọn model

Sau khi cấu hình xong, tất cả các model Ollama của các bạn đều có sẵn:

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

Nâng cao

Reasoning models

OpenClaw đánh dấu các model có khả năng reasoning khi Ollama báo cáo thinking trong /api/show:

ollama pull deepseek-r1:32b

Chi phí model

Ollama miễn phí và chạy cục bộ, nên tất cả chi phí model đều được set về $0.

Context windows

Đối với các model tự động phát hiện, OpenClaw sử dụng context window do Ollama báo cáo khi có sẵn, nếu không sẽ mặc định là 8192. Các bạn có thể override contextWindow và maxTokens trong config provider rõ ràng.

Troubleshooting

Ollama không được phát hiện

Đảm bảo Ollama đang chạy và các bạn đã set OLLAMA_API_KEY (hoặc auth profile), và các bạn không định nghĩa entry models.providers.ollama rõ ràng:

ollama serve

Và API có thể truy cập được:

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

Không có model nào

OpenClaw chỉ tự động phát hiện các model báo cáo hỗ trợ tool. Nếu model của các bạn không được liệt kê, thì:

  • Pull một model có khả năng tool, hoặc
  • Định nghĩa model một cách rõ ràng trong models.providers.ollama.

Để thêm model:

ollama list  # Xem những gì đã cài
ollama pull llama3.3  # Pull một model

Connection refused

Kiểm tra xem Ollama có đang chạy trên đúng port không:

# Kiểm tra xem Ollama có đang chạy không
ps aux | grep ollama

# Hoặc restart Ollama
ollama serve

Xem thêm