Providers
추론함
inferrs는 OpenAI 호환 /v1 API 뒤에서 로컬 모델을 제공할 수 있습니다. OpenClaw는 범용 openai-completions 경로를 통해 inferrs와 함께 작동합니다.
| 속성 | 값 |
|---|---|
| 제공자 ID | inferrs(사용자 지정; models.providers.inferrs 아래에서 구성) |
| Plugin | 없음 — inferrs는 번들 OpenClaw 제공자 plugin이 아닙니다 |
| 인증 환경 변수 | 선택 사항. inferrs 서버에 인증이 없으면 어떤 값이든 작동합니다 |
| API | OpenAI 호환(openai-completions) |
| 권장 기본 URL | http://127.0.0.1:8080/v1(또는 inferrs 서버가 있는 위치) |
시작하기
모델로 inferrs 시작
inferrs serve google/gemma-4-E2B-it \ --host 127.0.0.1 \ --port 8080 \ --device metal서버에 연결할 수 있는지 확인
curl http://127.0.0.1:8080/healthcurl http://127.0.0.1:8080/v1/modelsOpenClaw 제공자 항목 추가
명시적 제공자 항목을 추가하고 기본 모델이 이를 가리키도록 설정합니다. 아래 전체 구성 예시를 참조하세요.
전체 구성 예시
이 예시는 로컬 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를 사용하고
그 경로를 구성에 넣으세요. 전체 필드 참조는
로컬 모델 서비스를 참조하세요.
고급 구성
requiresStringContent가 중요한 이유
일부 inferrs Chat Completions 경로는 구조화된 콘텐츠 부분 배열이 아니라 문자열
messages[].content만 허용합니다.
compat: { requiresStringContent: true}OpenClaw는 요청을 보내기 전에 순수 텍스트 콘텐츠 부분을 일반 문자열로 평탄화합니다.
Gemma 및 도구 스키마 주의 사항
일부 현재 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, Responsesstore, 프롬프트 캐시 힌트, OpenAI 추론 호환 페이로드 형성이 없습니다- 숨겨진 OpenClaw 출처 표시 헤더(
originator,version,User-Agent)는 사용자 지정inferrs기본 URL에 주입되지 않습니다
문제 해결
curl /v1/models 실패
inferrs가 실행 중이 아니거나, 연결할 수 없거나, 예상한
호스트/포트에 바인딩되어 있지 않습니다. 서버가 시작되어 구성한 주소에서
수신 중인지 확인하세요.
messages[].content에 문자열이 필요함
모델 항목에 compat.requiresStringContent: true를 설정하세요. 자세한 내용은 위의
requiresStringContent 섹션을 참조하세요.
직접 /v1/chat/completions 호출은 통과하지만 openclaw infer model run은 실패함
도구 스키마 표면을 비활성화하려면 compat.supportsTools: false 설정을 시도하세요.
위의 Gemma 도구 스키마 주의 사항을 참조하세요.
더 큰 에이전트 턴에서 inferrs가 여전히 충돌함
OpenClaw에서 더 이상 스키마 오류가 발생하지 않지만 inferrs가 더 큰
에이전트 턴에서 여전히 충돌한다면, 이를 업스트림 inferrs 또는 모델 제한으로 간주하세요. 프롬프트
부담을 줄이거나 다른 로컬 백엔드 또는 모델로 전환하세요.