inferrs Provider

기준일: 2026-07-26
난이도: 중급
공식 기준: Inferrs

개요

이 페이지는 OpenClaw inferrs provider의 인증, 모델 ref, 온보딩 플래그, 설정 키를 공식 문서 기준으로 정리합니다.

공식 요약: Run OpenClaw through inferrs (OpenAI-compatible local server)

model ref는 보통 provider/model 형식입니다. API key·endpoint·model id는 아래 원문 값을 그대로 쓰세요. 임의로 키나 엔드포인트를 만들지 마세요.

빠른 참조

Property	Value
Provider id	inferrs (custom; configure under models.providers.inferrs)
Plugin	none — not a bundled OpenClaw provider plugin
Auth env var	none required; any value works if your inferrs server has no auth
API	OpenAI-compatible (openai-completions)
Suggested base URL	http://127.0.0.1:8080/v1 (or wherever your inferrs server listens)

공식 문서 기반 상세

아래는 공식 providers/inferrs 문서를 Mintlify 컴포넌트만 정리하고 공통 제목을 한국어로 맞춘 내용입니다. 설정 키, env, model ref, CLI 플래그는 원문 그대로 유지합니다.

inferrs serves local models behind an OpenAI-compatible /v1 API. OpenClaw talks to it through the generic openai-completions adapter.

Property	Value
Provider id	inferrs (custom; configure under models.providers.inferrs)
Plugin	none — not a bundled OpenClaw provider plugin
Auth env var	none required; any value works if your inferrs server has no auth
API	OpenAI-compatible (openai-completions)
Suggested base URL	http://127.0.0.1:8080/v1 (or wherever your inferrs server listens)

inferrs is a custom self-hosted OpenAI-compatible backend, not a dedicated OpenClaw provider plugin: you configure it under models.providers.inferrs instead of picking an onboarding auth choice. For a bundled plugin with auto-discovery, see SGLang or vLLM.

시작하기

Start inferrs with a model

```bash
inferrs serve google/gemma-4-E2B-it \
  --host 127.0.0.1 \
  --port 8080 \
  --device metal
```

Verify the server is reachable

```bash
curl http://127.0.0.1:8080/health
curl http://127.0.0.1:8080/v1/models
```

Add an OpenClaw provider entry

Add an explicit provider entry and point your default model at it. See the config example below.

Full config example

Gemma 4 on a local inferrs server:

{
  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 startup

OpenClaw can start inferrs itself only when an inferrs/... model is selected. Add localService to the same provider entry:

{
  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 must be an absolute path. Run which inferrs on the Gateway host and use that path. Full field reference: Local model services.

고급 설정

Why requiresStringContent matters

Some `inferrs` Chat Completions routes accept only string `messages[].content`, not structured content-part arrays.

If OpenClaw runs fail with:

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

set `compat.requiresStringContent: true` in the model entry. OpenClaw then flattens pure text content parts into plain strings before sending the request.

Gemma and tool-schema caveat

Some `inferrs` + Gemma combinations accept small direct `/v1/chat/completions` requests but fail on full OpenClaw agent-runtime turns. Try disabling the tool schema surface first:

```json5
compat: {
  requiresStringContent: true,
  supportsTools: false
}
```

That reduces prompt pressure on stricter local backends. If tiny direct requests still work but normal OpenClaw agent turns keep crashing inside `inferrs`, treat it as an upstream model/server limitation rather than an OpenClaw transport issue.

Manual smoke test

Test both layers once configured:

```bash
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}'
```

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

If the first command works but the second fails, see Troubleshooting below.

Proxy-style behavior

Because `inferrs` uses the generic `openai-completions` adapter (not `openai-responses`), native-OpenAI-only request shaping never applies: no `service_tier`, no Responses `store`, no prompt-cache hints, and no OpenAI reasoning-compat payload shaping get sent.

문제 해결

curl /v1/models fails

`inferrs` is not running, not reachable, or not bound to the host/port you configured. Confirm the server is started and listening on that address.

messages[].content expected a string

Set `compat.requiresStringContent: true` in the model entry (see above).

Direct /v1/chat/completions calls pass but openclaw infer model run fails

Set `compat.supportsTools: false` to disable the tool schema surface (see the Gemma caveat above).

inferrs still crashes on larger agent turns

If schema errors are gone but `inferrs` still crashes on larger agent turns, treat it as an upstream `inferrs` or model limitation. Reduce prompt pressure or switch backend/model.

For general help, see Troubleshooting and FAQ.

관련 문서

Running OpenClaw against local model servers.


Starting local model servers on demand for configured providers.


Debugging local OpenAI-compatible backends that pass probes but fail agent runs.


Overview of all providers, model refs, and failover behavior.

검증 체크리스트

• openclaw models list --provider inferrs 로 모델이 보이는지 확인
• 기본 model alias를 agents.defaults.model.primary에 설정했는지 확인
• API key / OAuth / 로컬 런타임 인증 경로를 공식 문서와 대조했는지 확인
• failover 시 데이터가 다른 provider로 이동할 수 있는지 검토

관련

• Provider 목록 인덱스
• 로컬 모델과 Provider
• 공식: Provider directory, Model providers