Mô hình cục bộ

​

Mức phần cứng tối thiểu

​

Chọn backend

​

Khuyến nghị: LM Studio + mô hình cục bộ lớn (Responses API)

{
  agents: {
    defaults: {
      model: { primary: "lmstudio/my-local-model" },
      models: {
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "lmstudio/my-local-model": { alias: "Local" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

• Cài đặt LM Studio: https://lmstudio.ai
• Trong LM Studio, tải xuống bản dựng mô hình lớn nhất có sẵn (tránh các biến thể “small”/bị lượng tử hóa nặng), khởi động máy chủ, xác nhận http://127.0.0.1:1234/v1/models liệt kê mô hình đó.
• Thay my-local-model bằng ID mô hình thực tế hiển thị trong LM Studio.
• Giữ mô hình ở trạng thái đã tải; tải nguội sẽ làm tăng độ trễ khởi động.
• Điều chỉnh contextWindow/maxTokens nếu bản dựng LM Studio của bạn khác.
• Với WhatsApp, hãy dùng Responses API để chỉ văn bản cuối cùng được gửi đi.

​

Cấu hình lai: hosted làm chính, cục bộ làm fallback

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["lmstudio/my-local-model", "anthropic/claude-opus-4-6"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "lmstudio/my-local-model": { alias: "Local" },
        "anthropic/claude-opus-4-6": { alias: "Opus" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

​

Ưu tiên cục bộ với lưới an toàn hosted

​

Hosting theo khu vực / định tuyến dữ liệu

• Các biến thể MiniMax/Kimi/GLM hosted cũng có trên OpenRouter với endpoint ghim theo khu vực (ví dụ: hosted tại Hoa Kỳ). Chọn biến thể theo khu vực ở đó để giữ lưu lượng trong vùng pháp lý bạn chọn trong khi vẫn dùng models.mode: "merge" cho fallback Anthropic/OpenAI.
• Chỉ cục bộ vẫn là đường dẫn riêng tư mạnh nhất; định tuyến hosted theo khu vực là phương án trung gian khi bạn cần tính năng của provider nhưng muốn kiểm soát luồng dữ liệu.

​

Các proxy cục bộ tương thích OpenAI khác

{
  agents: {
    defaults: {
      model: { primary: "local/my-local-model" },
    },
  },
  models: {
    mode: "merge",
    providers: {
      local: {
        baseUrl: "http://127.0.0.1:8000/v1",
        apiKey: "sk-local",
        api: "openai-completions",
        timeoutSeconds: 300,
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 120000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

• models.providers.mlx.models[].id: "mlx-community/Qwen3-30B-A3B-6bit"
• agents.defaults.model.primary: "mlx/mlx-community/Qwen3-30B-A3B-6bit"

• OpenClaw xử lý chúng như các route tương thích OpenAI kiểu proxy, không phải endpoint OpenAI gốc
• định hình yêu cầu chỉ dành cho OpenAI gốc không áp dụng ở đây: không có service_tier, không có Responses store, không định hình payload tương thích reasoning của OpenAI, và không có gợi ý prompt-cache
• các header phân bổ ẩn của OpenClaw (originator, version, User-Agent) không được chèn vào các URL proxy tùy chỉnh này

• Một số máy chủ chỉ chấp nhận messages[].content dạng chuỗi trên Chat Completions, không chấp nhận mảng structured content-part. Đặt models.providers.<provider>.models[].compat.requiresStringContent: true cho các endpoint đó.
• Một số mô hình cục bộ phát ra yêu cầu công cụ độc lập trong ngoặc vuông dưới dạng văn bản, chẳng hạn [tool_name] theo sau là JSON và [END_TOOL_REQUEST]. OpenClaw chỉ nâng cấp chúng thành lệnh gọi công cụ thật khi tên khớp chính xác với một công cụ đã đăng ký cho lượt đó; nếu không, khối này được xử lý là văn bản không được hỗ trợ và bị ẩn khỏi phản hồi hiển thị với người dùng.
• Nếu mô hình phát ra JSON, XML hoặc văn bản kiểu ReAct trông giống lệnh gọi công cụ nhưng provider không phát ra invocation có cấu trúc, OpenClaw giữ nguyên dưới dạng văn bản và ghi cảnh báo kèm run id, provider/model, mẫu phát hiện được và tên công cụ khi có. Hãy xem đó là sự không tương thích tool-call của provider/model, không phải một tool run đã hoàn tất.
• Nếu công cụ xuất hiện dưới dạng văn bản assistant thay vì chạy, ví dụ JSON thô, XML, cú pháp ReAct hoặc mảng tool_calls rỗng trong phản hồi provider, trước tiên hãy xác minh máy chủ đang dùng chat template/parser có khả năng tool-call. Với các backend Chat Completions tương thích OpenAI mà parser chỉ hoạt động khi tool use bị ép buộc, hãy đặt override yêu cầu theo từng mô hình thay vì dựa vào phân tích văn bản:
  {
    agents: {
      defaults: {
        models: {
          "local/my-local-model": {
            params: {
              extra_body: {
                tool_choice: "required",
              },
            },
          },
        },
      },
    },
  }
  
  Chỉ dùng điều này cho các mô hình/phiên mà mọi lượt thông thường đều nên gọi công cụ. Nó ghi đè giá trị proxy mặc định của OpenClaw là tool_choice: "auto". Thay local/my-local-model bằng provider/model ref chính xác được hiển thị bởi openclaw models list.
  openclaw config set agents.defaults.models '{"local/my-local-model":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge
  
• Nếu một mô hình tùy chỉnh tương thích OpenAI chấp nhận các mức nỗ lực reasoning của OpenAI ngoài profile tích hợp, hãy khai báo chúng trên khối compat của mô hình. Thêm "xhigh" ở đây sẽ khiến /think xhigh, trình chọn phiên, xác thực Gateway và xác thực llm-task hiển thị mức đó cho provider/model ref đã cấu hình:
  {
    models: {
      providers: {
        local: {
          baseUrl: "http://127.0.0.1:8000/v1",
          apiKey: "sk-local",
          api: "openai-responses",
          models: [
            {
              id: "gpt-5.4",
              name: "GPT 5.4 via local proxy",
              reasoning: true,
              input: ["text"],
              cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
              contextWindow: 196608,
              maxTokens: 8192,
              compat: {
                supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],
                reasoningEffortMap: { xhigh: "xhigh" },
              },
            },
          ],
        },
      },
    },
  }
  

​

Phần phụ trợ nhỏ hơn hoặc nghiêm ngặt hơn

1. Xác nhận chính mô hình cục bộ có phản hồi. Không có công cụ, không có ngữ cảnh tác nhân:
   openclaw infer model run --local --model <provider/model> --prompt "Reply with exactly: pong" --json
   
2. Xác nhận định tuyến Gateway. Chỉ gửi prompt được cung cấp — bỏ qua bản ghi hội thoại, khởi động AGENTS, lắp ráp công cụ ngữ cảnh, công cụ và các máy chủ MCP đi kèm, nhưng vẫn kiểm tra định tuyến Gateway, xác thực và lựa chọn nhà cung cấp:
   openclaw infer model run --gateway --model <provider/model> --prompt "Reply with exactly: pong" --json
   
3. Thử chế độ gọn nhẹ. Nếu cả hai phép kiểm tra đều đạt nhưng các lượt tác nhân thực tế thất bại với lệnh gọi công cụ sai định dạng hoặc prompt quá lớn, hãy bật agents.defaults.experimental.localModelLean: true. Chế độ này bỏ ba công cụ mặc định nặng nhất (browser, cron, message) và đặt các danh mục công cụ lớn hơn sau các điều khiển Tìm kiếm Công cụ có cấu trúc, ngoại trừ những lượt chạy bắt buộc phải giữ ngữ nghĩa gửi message trực tiếp. Xem Tính năng thử nghiệm → Chế độ gọn nhẹ cho mô hình cục bộ để biết giải thích đầy đủ, khi nào nên dùng và cách xác nhận chế độ này đang bật.
4. Tắt hoàn toàn công cụ như phương án cuối cùng. Nếu chế độ gọn nhẹ vẫn chưa đủ, hãy đặt models.providers.<provider>.models[].compat.supportsTools: false cho mục mô hình đó. Khi đó tác nhân sẽ hoạt động không có lệnh gọi công cụ trên mô hình đó.
5. Sau đó, nút thắt nằm ở thượng nguồn. Nếu phần phụ trợ vẫn chỉ thất bại trên các lượt chạy OpenClaw lớn hơn sau chế độ gọn nhẹ và supportsTools: false, vấn đề còn lại thường là năng lực của mô hình hoặc máy chủ thượng nguồn — cửa sổ ngữ cảnh, bộ nhớ GPU, loại bỏ kv-cache hoặc lỗi phần phụ trợ. Tại thời điểm đó, đây không còn là lớp truyền tải của OpenClaw.

​

Khắc phục sự cố

• Gateway có thể truy cập proxy không? curl http://127.0.0.1:1234/v1/models.
• Mô hình LM Studio đã bị dỡ tải? Tải lại; khởi động nguội là một nguyên nhân “treo” phổ biến.
• Máy chủ cục bộ báo terminated, ECONNRESET hoặc đóng luồng giữa lượt? OpenClaw ghi lại model.call.error.failureKind có số lượng giá trị thấp cùng với ảnh chụp nhanh RSS/heap của tiến trình OpenClaw trong chẩn đoán. Với áp lực bộ nhớ của LM Studio/Ollama, hãy đối chiếu dấu thời gian đó với nhật ký máy chủ hoặc nhật ký crash / jetsam của macOS để xác nhận máy chủ mô hình có bị kết thúc hay không.
• OpenClaw suy ra các ngưỡng kiểm tra trước cửa sổ ngữ cảnh từ cửa sổ mô hình được phát hiện, hoặc từ cửa sổ mô hình chưa giới hạn khi agents.defaults.contextTokens hạ thấp cửa sổ hiệu dụng. OpenClaw cảnh báo dưới 20% với sàn 8k. Chặn cứng dùng ngưỡng 10% với sàn 4k, được giới hạn theo cửa sổ ngữ cảnh hiệu dụng để siêu dữ liệu mô hình quá lớn không thể từ chối một giới hạn người dùng vốn hợp lệ. Nếu gặp kiểm tra trước đó, hãy tăng giới hạn ngữ cảnh máy chủ/mô hình hoặc chọn mô hình lớn hơn.
• Lỗi ngữ cảnh? Giảm contextWindow hoặc tăng giới hạn máy chủ của bạn.
• Máy chủ tương thích OpenAI trả về messages[].content ... expected a string? Thêm compat.requiresStringContent: true vào mục mô hình đó.
• Máy chủ tương thích OpenAI trả về validation.keys hoặc nói các mục tin nhắn chỉ cho phép role và content? Thêm compat.strictMessageKeys: true vào mục mô hình đó.
• Các lệnh gọi /v1/chat/completions trực tiếp và rất nhỏ hoạt động, nhưng openclaw infer model run --local thất bại trên Gemma hoặc một mô hình cục bộ khác? Trước tiên hãy kiểm tra URL nhà cung cấp, tham chiếu mô hình, dấu hiệu xác thực và nhật ký máy chủ; model run cục bộ không bao gồm công cụ tác nhân. Nếu model run cục bộ thành công nhưng các lượt tác nhân lớn hơn thất bại, hãy giảm bề mặt công cụ của tác nhân bằng localModelLean hoặc compat.supportsTools: false.
• Lệnh gọi công cụ xuất hiện dưới dạng văn bản JSON/XML/ReAct thô, hoặc nhà cung cấp trả về mảng tool_calls rỗng? Đừng thêm proxy chuyển đổi mù quáng văn bản của trợ lý thành thực thi công cụ. Trước tiên hãy sửa mẫu/phân tích cú pháp chat của máy chủ. Nếu mô hình chỉ hoạt động khi bắt buộc dùng công cụ, hãy thêm phần ghi đè theo từng mô hình params.extra_body.tool_choice: "required" ở trên và chỉ dùng mục mô hình đó cho các phiên mà mỗi lượt đều dự kiến có lệnh gọi công cụ.
• An toàn: mô hình cục bộ bỏ qua bộ lọc phía nhà cung cấp; giữ tác nhân ở phạm vi hẹp và bật Compaction để giới hạn phạm vi ảnh hưởng của chèn prompt.

​

Liên quan

• Tham chiếu cấu hình
• Chuyển đổi dự phòng mô hình