메인 콘텐츠로 건너뛰기

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

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

inferrs는 OpenAI 호환 /v1 API 뒤에서 로컬 모델을 제공할 수 있습니다. OpenClaw는 범용 openai-completions 경로를 통해 inferrs와 함께 작동합니다.
속성값
제공자 IDinferrs(사용자 지정; models.providers.inferrs 아래에서 구성)
Plugin없음 — inferrs는 번들 OpenClaw 제공자 plugin이 아닙니다
인증 환경 변수선택 사항. inferrs 서버에 인증이 없으면 어떤 값이든 작동합니다
APIOpenAI 호환(openai-completions)
권장 기본 URLhttp://127.0.0.1:8080/v1(또는 inferrs 서버가 있는 위치)
현재 inferrs는 전용 OpenClaw 제공자 plugin이 아니라 사용자 지정 자체 호스팅 OpenAI 호환 백엔드로 다루는 것이 가장 좋습니다. 온보딩 선택 플래그가 아니라 models.providers.inferrs를 통해 구성합니다. 자동 검색 기능이 있는 실제 번들 plugin이 필요하면 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는 절대 경로여야 합니다. Gateway 호스트에서 which inferrs를 사용하고 그 경로를 구성에 넣으세요. 전체 필드 참조는 로컬 모델 서비스를 참조하세요.

​
고급 구성

일부 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 에이전트 런타임 턴에서는 여전히 실패합니다.이 경우 먼저 다음을 시도하세요.
compat: {
  requiresStringContent: true,
  supportsTools: false
}
그러면 해당 모델에 대한 OpenClaw의 도구 스키마 표면이 비활성화되어 더 엄격한 로컬 백엔드의 프롬프트 부담을 줄일 수 있습니다.아주 작은 직접 요청은 여전히 작동하지만 일반 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 엔드포인트가 아니라 프록시 스타일 OpenAI 호환 /v1 백엔드로 처리됩니다.
  • 네이티브 OpenAI 전용 요청 형성은 여기에 적용되지 않습니다
  • service_tier, Responses store, 프롬프트 캐시 힌트, OpenAI 추론 호환 페이로드 형성이 없습니다
  • 숨겨진 OpenClaw 출처 표시 헤더(originator, version, User-Agent)는 사용자 지정 inferrs 기본 URL에 주입되지 않습니다

​
문제 해결

inferrs가 실행 중이 아니거나, 연결할 수 없거나, 예상한 호스트/포트에 바인딩되어 있지 않습니다. 서버가 시작되어 구성한 주소에서 수신 중인지 확인하세요.
모델 항목에 compat.requiresStringContent: true를 설정하세요. 자세한 내용은 위의 requiresStringContent 섹션을 참조하세요.
도구 스키마 표면을 비활성화하려면 compat.supportsTools: false 설정을 시도하세요. 위의 Gemma 도구 스키마 주의 사항을 참조하세요.
OpenClaw에서 더 이상 스키마 오류가 발생하지 않지만 inferrs가 더 큰 에이전트 턴에서 여전히 충돌한다면, 이를 업스트림 inferrs 또는 모델 제한으로 간주하세요. 프롬프트 부담을 줄이거나 다른 로컬 백엔드 또는 모델로 전환하세요.
일반적인 도움말은 문제 해결 및 FAQ를 참조하세요.

​
관련 항목

로컬 모델

로컬 모델 서버에 대해 OpenClaw 실행.

로컬 모델 서비스

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

Gateway 문제 해결

프로브는 통과하지만 에이전트 실행에서 실패하는 로컬 OpenAI 호환 백엔드 디버깅.

모델 선택

모든 제공자, 모델 참조, 장애 조치 동작 개요.