Skip to main content

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

inferrs 可以在一个兼容 OpenAI 的 /v1 API 后面提供本地模型服务。OpenClaw 通过通用的 openai-completions 路径与 inferrs 协同工作。 目前最好将 inferrs 视为一个自托管的、兼容 OpenAI 的 后端，而不是一个专门的 OpenClaw 提供方插件。

​
快速开始

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 Chat Completions 路由只接受字符串类型的 messages[].content，而不接受结构化的内容分块数组。
如果 OpenClaw 运行失败，并出现如下错误：
messages[1].content: invalid type: sequence, expected a string
请在你的模型条目中设置 compat.requiresStringContent: true。
compat: {
  requiresStringContent: true
}
在发送请求之前，OpenClaw 会将纯文本内容分块展平成普通字符串。
某些当前的 inferrs + Gemma 组合可以接受较小的直接 /v1/chat/completions 请求，但在完整的 OpenClaw agent-runtime 轮次中仍然会失败。如果发生这种情况，先尝试以下配置：
compat: {
  requiresStringContent: true,
  supportsTools: false
}
这会禁用该模型的 OpenClaw 工具 schema 表面，并且可以减少对更严格的本地后端造成的提示词 压力。如果较小的直接请求仍然可用，但正常的 OpenClaw agent 轮次继续在 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 提示，也没有 OpenAI reasoning-compat 负载整形
  • 隐藏的 OpenClaw 归属头（originator、version、User-Agent） 不会注入到自定义 inferrs base URL 中

​
故障排除

inferrs 没有运行、无法访问，或者没有绑定到预期的 host/port。请确保服务器已启动并正在监听你配置的地址。
在模型条目中设置 compat.requiresStringContent: true。有关详细信息，请参见上文 requiresStringContent 部分。
尝试设置 compat.supportsTools: false 以禁用工具 schema 表面。 请参见上面的 Gemma 工具 schema 注意事项。
如果 OpenClaw 不再出现 schema 错误，但 inferrs 在较大的 agent 轮次中仍然崩溃，则应将其视为上游 inferrs 或模型限制。请降低 提示词压力，或切换到不同的本地后端或模型。
如需一般帮助，请参阅 故障排除 和 FAQ。

​
相关内容

本地模型

在本地模型服务器上运行 OpenClaw。

网关故障排除

调试那些能够通过探测但在 agent 运行时失败的本地 OpenAI 兼容后端。

模型选择

所有提供方、模型引用和故障转移行为的概览。