추론함

inferrs는 OpenAI 호환 /v1 API를 통해 로컬 모델을 제공합니다. OpenClaw는 범용 openai-completions 어댑터를 통해 이 API와 통신합니다.

속성	값
제공자 ID	`inferrs`(사용자 정의, `models.providers.inferrs`에서 구성)
Plugin	없음 — OpenClaw에 번들로 포함된 제공자 Plugin이 아님
인증 환경 변수	필요 없음. inferrs 서버에 인증이 없으면 어떤 값이든 사용 가능
API	OpenAI 호환(`openai-completions`)
권장 기본 URL	`http://127.0.0.1:8080/v1`(또는 inferrs 서버가 수신 대기하는 위치)

inferrs는 전용 OpenClaw 제공자 Plugin이 아니라 사용자 정의 자체 호스팅 OpenAI 호환 백엔드입니다. 따라서 온보딩 인증 선택 항목에서 고르는 대신 models.providers.inferrs에서 구성합니다. 자동 검색 기능을 제공하는 번들 Plugin은 SGLang 또는 vLLM을 참조하세요.

시작하기

모델과 함께 inferrs 시작

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

서버에 연결할 수 있는지 확인

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

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,
            },
          },
        ],
      },
    },
  },
}

주문형 시작

OpenClaw는 inferrs/... 모델이 선택된 경우에만 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는 절대 경로여야 합니다. Gateway 호스트에서 which inferrs를 실행하고 해당 경로를 사용하세요. 전체 필드 참조: 로컬 모델 서비스.

고급 구성

requiresStringContent가 중요한 이유

일부 inferrs Chat Completions 경로는 구조화된 콘텐츠 부분 배열이 아니라 문자열 형식의 messages[].content만 허용합니다.

OpenClaw 실행이 다음 오류와 함께 실패하는 경우:

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

모델 항목에 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":"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-responses가 아닌 범용 openai-completions 어댑터를 사용하므로 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를 실행합니다.

로컬 모델 서비스

구성된 제공자를 위해 필요할 때 로컬 모델 서버를 시작합니다.

Gateway 문제 해결

직접 검사는 통과하지만 에이전트 실행은 실패하는 로컬 OpenAI 호환 백엔드를 디버깅합니다.

모델 선택

모든 제공자, 모델 참조 및 장애 조치 동작을 살펴봅니다.

Overview

Concepts and configuration

Providers

시작하기

전체 구성 예시

주문형 시작

고급 구성

문제 해결

관련 항목

로컬 모델

로컬 모델 서비스

Gateway 문제 해결

모델 선택

​시작하기

​전체 구성 예시

​주문형 시작

​고급 구성

​문제 해결

​관련 항목

로컬 모델

로컬 모델 서비스

Gateway 문제 해결

모델 선택

시작하기

전체 구성 예시

주문형 시작

고급 구성

문제 해결

관련 항목