Providers
추론함
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 시작
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, }, }, ], }, }, },}주문형 시작
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만 허용합니다.
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 또는 모델의 제한으로 간주하세요. 프롬프트 부담을 줄이거나 백엔드 또는 모델을 변경하세요.
