OpenClaw 可通过 OpenAI 兼容路径连接本地 inferrs 服务器，适合离线或隐私场景。需手动配置 models.providers.inferrs，指定 api 为 openai-completions，并设置 compat.requiresStringContent: true 避免内容格式错误。可配置 on-demand 自动启动，注意 command 必须为绝对路径。若代理运行时失败，可尝试禁用 tool schema。

OpenClaw inferrs 配置：本地模型接入与故障排查

inferrs 是一个本地模型服务器，提供 OpenAI 兼容的 /v1 API。OpenClaw 通过通用 openai-completions 路径与它对接。

属性	值
Provider id	inferrs（自定义；配置在 models.providers.inferrs 下）
插件	无 — inferrs 不是 OpenClaw 自带的 provider 插件
认证环境变量	可选。如果你的 inferrs 服务器没有认证，任何值都行
API	OpenAI 兼容（openai-completions）
推荐 base URL	http://127.0.0.1:8080/v1（或你的 inferrs 服务器实际地址）

TIP

inferrs 目前最适合作为自托管的自定义 OpenAI 兼容后端，而不是 OpenClaw 专用 provider 插件。你需要在 models.providers.inferrs 下手动配置，而不是通过 onboard 选项选择。如果你需要自带自动发现的 bundle 插件，请参考 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 中添加 provider 配置
   显式添加 provider 条目，并将默认模型指向它。完整示例如下。

完整配置示例

以下示例使用本地 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,
            },
          },
        ],
      },
    },
  },
}

On-demand 自动启动

可以让 OpenClaw 在选中 inferrs/... 模型时才启动 inferrs。在同一个 provider 条目中添加 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 必须是绝对路径。在 Gateway 主机上运行 which inferrs，将结果填入配置。全部字段参考请见 本地模型服务。

高级配置

为什么 requiresStringContent 很重要

部分 inferrs 的 Chat Completions 路由只接受字符串类型的 messages[].content，不接受结构化的 content-part 数组。

WARNING

如果 OpenClaw 运行时出现如下错误：

messages[1].content: invalid type: sequence, expected a string

请在模型配置中设置 compat.requiresStringContent: true。

compat: {
  requiresStringContent: true
}

OpenClaw 会在发送请求前将纯文本 content part 扁平化为普通字符串。 :::

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":"What is 2 + 2?"}],"stream":false}'

openclaw infer model run \
  --model inferrs/google/gemma-4-E2B-it \
  --prompt "What is 2 + 2? Reply with one short sentence." \
  --json

如果第一个命令成功但第二个失败，请查看下面的故障排查章节。

代理模式行为

inferrs 被视为代理风格的 OpenAI 兼容 /v1 后端，而非原生 OpenAI 端点。

• 原生 OpenAI 独有的请求整形不适用
• 不支持 service_tier、Responses store、prompt-cache 提示
• OpenClaw 的隐藏属性头（originator、version、User-Agent）不会注入到自定义 inferrs base URL

故障排查

curl /v1/models 失败

inferrs 未运行、不可达或没有绑定到预期的 host/port。请确认服务器已经启动并监听你配置的地址。

messages[].content expected a string 错误

在模型配置中设置 compat.requiresStringContent: true。详见上述 “requiresStringContent” 章节。

直接 /v1/chat/completions 调用通过，但 openclaw infer model run 失败

尝试设置 compat.supportsTools: false 以禁用工具模式描述。参见上述 “Gemma 工具模式” 章节。

inferrs 在较大智能体回合中仍然崩溃

如果 OpenClaw 不再出现模式错误，但 inferrs 仍在较大回合中崩溃，通常是上游 inferrs 或模型的限制。尝试降低提示压力，或切换到其他本地后端/模型。

TIP

通用帮助请参考 故障排查 和 FAQ。

相关文档

本地模型

在 OpenClaw 中连接本地模型服务器。

本地模型服务

按需启动本地模型服务器为配置的 provider 提供服务。

Gateway 故障排查

调试通过直接探测但智能体运行失败的本地 OpenAI 兼容后端。

模型选择

所有 provider、模型引用和故障切换行为概览。

常见问题

curl /v1/models 失败怎么办？

确保 inferrs 服务器已经启动，并且绑定到配置文件中指定的 host 和 port。可以用 curl http://127.0.0.1:8080/health 先测试基础可达性。

OpenClaw 调用 inferrs 时报错 "messages[].content expected a string" 如何解决？

在模型的 compat 字段中设置 requiresStringContent: true。OpenClaw 会将被拒绝的 content 数组自动压平为纯文本字符串。

直接用 curl 测试 /v1/chat/completions 正常，但 openclaw infer model run 失败怎么办？

尝试在模型 compat 中添加 supportsTools: false，禁用工具模式描述。如果问题持续，可能涉及模型/服务器的兼容性限制，考虑更换后端或模型。