Dịch vụ mô hình cục bộ

models.providers.<id>.localService khởi động máy chủ mô hình cục bộ do nhà cung cấp quản lý khi cần. Khi một yêu cầu mô hình hoặc embedding chọn nhà cung cấp đó, OpenClaw thăm dò điểm cuối kiểm tra tình trạng, khởi động tiến trình nếu máy chủ không hoạt động, chờ đến khi sẵn sàng rồi gửi yêu cầu. Hãy dùng tính năng này để tránh phải duy trì các máy chủ cục bộ tốn nhiều tài nguyên hoạt động cả ngày.

​

Cách hoạt động

1. Một yêu cầu mô hình hoặc embedding được phân giải tới nhà cung cấp đã cấu hình.
2. Nếu nhà cung cấp đó có localService, OpenClaw sẽ thăm dò healthUrl.
3. Nếu thăm dò thành công, OpenClaw sử dụng máy chủ đang chạy.
4. Nếu thăm dò thất bại, OpenClaw khởi chạy command với args.
5. OpenClaw thăm dò định kỳ điểm cuối kiểm tra tình trạng cho đến khi readyTimeoutMs hết hạn.
6. Yêu cầu đi qua cơ chế vận chuyển mô hình hoặc embedding thông thường.
7. Nếu OpenClaw đã khởi động tiến trình và idleStopMs được đặt, OpenClaw sẽ dừng tiến trình sau khi yêu cầu đang xử lý cuối cùng đã ở trạng thái nhàn rỗi trong khoảng thời gian đó.

OpenClaw không cài đặt launchd, systemd, Docker hay bất kỳ daemon nào cho việc này. Máy chủ chỉ là một tiến trình con thông thường của tiến trình OpenClaw đầu tiên cần đến nó.

Quá trình khởi động được tuần tự hóa theo từng nhà cung cấp đã cấu hình và từng tập hợp lệnh/đối số/biến môi trường, vì vậy các yêu cầu trò chuyện và embedding đồng thời dành cho cùng một dịch vụ sẽ không khởi chạy các máy chủ trùng lặp. Mỗi yêu cầu giữ phiên thuê riêng cho đến khi hoàn tất xử lý phản hồi, vì vậy quá trình tắt khi nhàn rỗi sẽ chờ mọi yêu cầu mô hình và embedding đang xử lý. Các bí danh nhà cung cấp đã cấu hình vẫn độc lập: hai bí danh có thể trỏ đến các máy chủ GPU khác nhau mà không bị gộp vào cùng một mã định danh bộ điều hợp Ollama, LM Studio hoặc tương thích với OpenAI.

Nếu một tiến trình OpenClaw khác đã có máy chủ hoạt động ổn định tại cùng healthUrl, tiến trình này sẽ tái sử dụng máy chủ đó mà không tiếp quản quyền quản lý (mỗi tiến trình chỉ quản lý tiến trình con do chính nó khởi động). Nhật ký khởi động và thoát bao gồm phần cuối đầu ra của tiến trình con có giới hạn và đã che dữ liệu nhạy cảm, cùng thông tin thời gian và chi tiết thoát; các giá trị môi trường đã cấu hình tuyệt đối không được xuất ra.

​

Cấu trúc cấu hình

{
  models: {
    providers: {
      local: {
        baseUrl: "http://127.0.0.1:8000/v1",
        apiKey: "local-model",
        api: "openai-completions",
        timeoutSeconds: 300,
        localService: {
          command: "/absolute/path/to/server",
          args: ["--host", "127.0.0.1", "--port", "8000"],
          cwd: "/absolute/path/to/working-dir",
          env: { LOCAL_MODEL_CACHE: "/absolute/path/to/cache" },
          healthUrl: "http://127.0.0.1:8000/v1/models",
          readyTimeoutMs: 180000,
          idleStopMs: 0,
        },
        models: [
          {
            id: "my-local-model",
            name: "My Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 131072,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

Đặt timeoutSeconds trong mục nhà cung cấp (không phải trong localService) để quá trình khởi động nguội chậm và quá trình tạo nội dung kéo dài không chạm ngưỡng hết thời gian chờ mặc định của yêu cầu mô hình. Hãy đặt healthUrl rõ ràng bất cứ khi nào máy chủ cung cấp trạng thái sẵn sàng tại vị trí khác với /models trên URL cơ sở.

​

Các trường

Trường	Bắt buộc	Mô tả
command	có	Đường dẫn tuyệt đối đến tệp thực thi. Không tra cứu trong PATH của shell.
args	không	Các đối số của tiến trình. Không hỗ trợ mở rộng shell, đường ống, ký tự đại diện hoặc dấu trích dẫn.
cwd	không	Thư mục làm việc của tiến trình.
env	không	Các biến môi trường được hợp nhất và ghi đè lên môi trường của tiến trình OpenClaw.
healthUrl	không	URL kiểm tra trạng thái sẵn sàng. Mặc định là baseUrl được nối thêm /models (http://127.0.0.1:8000/v1 trở thành http://127.0.0.1:8000/v1/models).
readyTimeoutMs	không	Thời hạn chờ trạng thái sẵn sàng khi khởi động. Mặc định: 120000.
idleStopMs	không	Độ trễ trước khi tắt do nhàn rỗi đối với tiến trình do OpenClaw khởi động. 0 hoặc bỏ qua trường này sẽ giữ tiến trình hoạt động cho đến khi OpenClaw thoát.

​

Ví dụ về Inferrs

Inferrs là một phần phụ trợ /v1 tùy chỉnh tương thích với OpenAI, vì vậy cùng API localService có thể hoạt động với một mục nhà cung cấp inferrs:

{
  agents: {
    defaults: {
      model: { primary: "inferrs/google/gemma-4-E2B-it" },
    },
  },
  models: {
    mode: "merge",
    providers: {
      inferrs: {
        baseUrl: "http://127.0.0.1:8080/v1",
        apiKey: "inferrs-local",
        api: "openai-completions",
        timeoutSeconds: 300,
        localService: {
          command: "/opt/homebrew/bin/inferrs",
          args: [
            "serve",
            "google/gemma-4-E2B-it",
            "--host",
            "127.0.0.1",
            "--port",
            "8080",
            "--device",
            "metal",
          ],
          healthUrl: "http://127.0.0.1:8080/v1/models",
          readyTimeoutMs: 180000,
          idleStopMs: 0,
        },
        models: [
          {
            id: "google/gemma-4-E2B-it",
            name: "Gemma 4 E2B (inferrs)",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 131072,
            maxTokens: 4096,
            compat: { requiresStringContent: true },
          },
        ],
      },
    },
  },
}

Thay command bằng kết quả của which inferrs trên máy chạy OpenClaw. Thiết lập inferrs đầy đủ: Inferrs.

​

Ví dụ về ds4

{
  models: {
    providers: {
      ds4: {
        baseUrl: "http://127.0.0.1:18000/v1",
        apiKey: "ds4-local",
        api: "openai-completions",
        timeoutSeconds: 300,
        localService: {
          command: "<DS4_DIR>/ds4-server",
          args: [
            "--model",
            "<DS4_DIR>/ds4flash.gguf",
            "--host",
            "127.0.0.1",
            "--port",
            "18000",
            "--ctx",
            "32768",
            "--tokens",
            "128",
          ],
          cwd: "<DS4_DIR>",
          healthUrl: "http://127.0.0.1:18000/v1/models",
          readyTimeoutMs: 300000,
          idleStopMs: 0,
        },
        models: [],
      },
    },
  },
}

Các lệnh thiết lập đầy đủ, định cỡ ngữ cảnh và xác minh: ds4.

​

Liên quan

Mô hình cục bộ

Cách thiết lập mô hình cục bộ, lựa chọn nhà cung cấp và hướng dẫn an toàn.

Inferrs

Chạy OpenClaw thông qua máy chủ cục bộ inferrs tương thích với OpenAI.