Inferrs

inferrs 透過與 OpenAI 相容的 /v1 API 提供本機模型。OpenClaw 透過通用 openai-completions 轉接器與其通訊。

屬性	值
提供者 ID	inferrs（自訂；於 models.providers.inferrs 下設定）
外掛	無 — 並非 OpenClaw 內建的提供者外掛
驗證環境變數	不需要；若你的 inferrs 伺服器未啟用驗證，任何值皆可使用
API	與 OpenAI 相容（openai-completions）
建議的基底 URL	http://127.0.0.1:8080/v1（或你的 inferrs 伺服器所監聽的位置）

inferrs 是自訂的自架式 OpenAI 相容後端，而非專用的 OpenClaw 提供者外掛：請在 models.providers.inferrs 下設定，而不是選擇上線引導中的驗證選項。若需要支援自動探索的內建外掛，請參閱 SGLang 或 vLLM。

​

開始使用

1. 使用模型啟動 inferrs

   inferrs serve google/gemma-4-E2B-it \
     --host 127.0.0.1 \
     --port 8080 \
     --device metal
   
2. 確認伺服器可連線

   curl http://127.0.0.1:8080/health
   curl http://127.0.0.1:8080/v1/models
   
3. 新增 OpenClaw 提供者項目

   新增明確的提供者項目，並將預設模型指向該項目。請參閱下方的設定範例。

​

完整設定範例

在本機 inferrs 伺服器上執行 Gemma 4：

{
  agents: {
    defaults: {
      model: { primary: "inferrs/google/gemma-4-E2B-it" },
      models: {
        "inferrs/google/gemma-4-E2B-it": {
          alias: "Gemma 4 (inferrs)",
        },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      inferrs: {
        baseUrl: "http://127.0.0.1:8080/v1",
        apiKey: "inferrs-local",
        api: "openai-completions",
        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,
            },
          },
        ],
      },
    },
  },
}

​

隨需啟動

只有選取 inferrs/... 模型時，OpenClaw 才能自行啟動 inferrs。請將 localService 新增至同一個提供者項目：

{
  models: {
    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,
            },
          },
        ],
      },
    },
  },
}

command 必須是絕對路徑。請在閘道主機上執行 which inferrs，並使用該路徑。完整欄位參考：本機模型服務。

​

進階設定

requiresStringContent 為何重要

某些 inferrs Chat Completions 路由僅接受字串 messages[].content，不接受結構化的內容部分陣列。

若 OpenClaw 執行失敗並顯示：

messages[1].content: 類型無效：應為字串，卻收到序列

請在模型項目中設定 compat.requiresStringContent: true。OpenClaw 隨後會在傳送請求前，將純文字內容部分攤平成純字串。

Gemma 與工具結構描述的注意事項

某些 inferrs + Gemma 組合可接受小型的直接 /v1/chat/completions 請求，但在完整的 OpenClaw 代理程式執行階段回合中會失敗。請先嘗試停用工具結構描述介面：

compat: {
  requiresStringContent: true,
  supportsTools: false
}

這可降低較嚴格本機後端的提示詞負荷。若微型直接請求仍可運作，但一般 OpenClaw 代理程式回合持續在 inferrs 內當機，請將其視為上游模型或伺服器限制，而非 OpenClaw 傳輸問題。

手動冒煙測試

完成設定後，請測試這兩層：

curl http://127.0.0.1:8080/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"google/gemma-4-E2B-it","messages":[{"role":"user","content":"2 + 2 是多少？"}],"stream":false}'

openclaw infer model run \
  --model inferrs/google/gemma-4-E2B-it \
  --prompt "2 + 2 是多少？請用一句簡短的句子回答。" \
  --json

若第一個命令可運作，但第二個失敗，請參閱下方的疑難排解。

代理式行為

由於 inferrs 使用通用 openai-completions 轉接器（而非 openai-responses），因此不會套用僅限原生 OpenAI 的請求塑形：不會傳送 service_tier、Responses store、提示詞快取提示，也不會傳送 OpenAI 推理相容性承載資料的塑形。

​

疑難排解

curl /v1/models 失敗

inferrs 未執行、無法連線，或未繫結至你所設定的主機或連接埠。請確認伺服器已啟動，並正在該位址上監聽。

messages[].content 預期為字串

請在模型項目中設定 compat.requiresStringContent: true（請參閱上方）。

直接呼叫 /v1/chat/completions 成功，但 openclaw infer model run 失敗

請設定 compat.supportsTools: false 以停用工具結構描述介面（請參閱上方的 Gemma 注意事項）。

inferrs 在較大的代理程式回合中仍會當機

若結構描述錯誤已消失，但 inferrs 在較大的代理程式回合中仍會當機，請將其視為上游 inferrs 或模型限制。請降低提示詞負荷，或切換後端或模型。

如需一般協助，請參閱疑難排解和常見問題。

​

相關內容

本機模型

使用本機模型伺服器執行 OpenClaw。

本機模型服務

為已設定的提供者隨需啟動本機模型伺服器。

閘道疑難排解

對通過探測但代理程式執行失敗的本機 OpenAI 相容後端進行偵錯。

模型選擇

所有提供者、模型參照及容錯移轉行為的概覽。