로컬 모델 서비스

models.providers.<id>.localService는 필요할 때 공급자 소유의 로컬 모델 서버를 시작합니다. 모델 또는 임베딩 요청에서 해당 공급자를 선택하면 OpenClaw는 상태 엔드포인트를 확인하고, 서버가 중지되어 있으면 프로세스를 시작한 뒤 준비될 때까지 기다렸다가 요청을 전송합니다. 비용이 많이 드는 로컬 서버를 하루 종일 실행하지 않으려는 경우 사용하세요.

작동 방식

모델 또는 임베딩 요청이 구성된 공급자로 해석됩니다.
해당 공급자에 localService가 있으면 OpenClaw가 healthUrl을 확인합니다.
확인에 성공하면 OpenClaw는 이미 실행 중인 서버를 사용합니다.
확인에 실패하면 OpenClaw는 args를 사용하여 command를 실행합니다.
OpenClaw는 readyTimeoutMs가 만료될 때까지 상태 엔드포인트를 폴링합니다.
요청은 일반적인 모델 또는 임베딩 전송 경로를 거칩니다.
OpenClaw가 프로세스를 시작했고 idleStopMs가 설정되어 있으면, 처리 중이던 마지막 요청이 해당 시간만큼 유휴 상태가 된 후 프로세스를 중지합니다.

OpenClaw는 이를 위해 launchd, systemd, Docker 또는 어떠한 데몬도 설치하지 않습니다. 서버는 이를 처음 필요로 한 OpenClaw 프로세스의 일반 자식 프로세스입니다. 시작 작업은 구성된 공급자와 명령/인수/환경 변수 집합별로 직렬화되므로 동일한 서비스를 대상으로 한 채팅 및 임베딩 요청이 동시에 발생해도 서버가 중복으로 생성되지 않습니다. 각 요청은 응답 처리가 완료될 때까지 자체 임대를 유지하므로, 유휴 종료는 처리 중인 모든 모델 및 임베딩 요청이 완료될 때까지 기다립니다. 구성된 공급자 별칭은 서로 구분된 상태로 유지됩니다. 두 별칭이 서로 다른 GPU 호스트를 가리키더라도 동일한 Ollama, LM Studio 또는 OpenAI 호환 어댑터 ID로 통합되지 않습니다. 다른 OpenClaw 프로세스가 동일한 healthUrl에서 이미 정상 상태의 서버를 실행 중이면 이 프로세스는 해당 서버의 관리를 인수하지 않고 재사용합니다(각 프로세스는 자신이 직접 시작한 자식 프로세스만 관리합니다). 시작 및 종료 로그에는 길이가 제한되고 민감 정보가 제거된 자식 프로세스 출력의 마지막 부분과 소요 시간 및 종료 세부 정보가 포함되며, 구성된 환경 변수 값은 절대 출력되지 않습니다.

구성 형태

{
  models: {
    providers: {
      local: {
        baseUrl: "http://127.0.0.1:8000/v1",
        apiKey: "local-model",
        api: "openai-completions",
        timeoutSeconds: 300,
        localService: {
          command: "/absolute/path/to/server",
          args: ["--host", "127.0.0.1", "--port", "8000"],
          cwd: "/absolute/path/to/working-dir",
          env: { LOCAL_MODEL_CACHE: "/absolute/path/to/cache" },
          healthUrl: "http://127.0.0.1:8000/v1/models",
          readyTimeoutMs: 180000,
          idleStopMs: 0,
        },
        models: [
          {
            id: "my-local-model",
            name: "My Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 131072,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

느린 콜드 스타트와 긴 생성 작업이 기본 모델 요청 제한 시간에 걸리지 않도록 공급자 항목에 timeoutSeconds를 설정하세요(localService가 아님). 서버가 기본 URL의 /models가 아닌 다른 위치에서 준비 상태를 제공하는 경우에는 명시적인 healthUrl을 설정하세요.

필드

필드	필수 여부	설명
`command`	예	실행 파일의 절대 경로입니다. 셸 PATH 조회를 수행하지 않습니다.
`args`	아니요	프로세스 인수입니다. 셸 확장, 파이프, 글로빙 또는 따옴표 처리를 수행하지 않습니다.
`cwd`	아니요	프로세스의 작업 디렉터리입니다.
`env`	아니요	OpenClaw 프로세스 환경에 병합되는 환경 변수입니다.
`healthUrl`	아니요	준비 상태 URL입니다. 기본값은 `baseUrl`에 `/models`를 추가한 값입니다(`http://127.0.0.1:8000/v1`은 `http://127.0.0.1:8000/v1/models`가 됩니다).
`readyTimeoutMs`	아니요	시작 준비 제한 시간입니다. 기본값: `120000`.
`idleStopMs`	아니요	OpenClaw가 시작한 프로세스의 유휴 종료 지연 시간입니다. `0`이거나 생략하면 OpenClaw가 종료될 때까지 계속 실행합니다.

Inferrs 예시

Inferrs는 사용자 지정 OpenAI 호환 /v1 백엔드이므로 동일한 localService API를 inferrs 공급자 항목에 사용할 수 있습니다.

{
  agents: {
    defaults: {
      model: { primary: "inferrs/google/gemma-4-E2B-it" },
    },
  },
  models: {
    mode: "merge",
    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를 OpenClaw가 실행되는 머신에서 which inferrs를 실행한 결과로 바꾸세요. 전체 inferrs 설정: Inferrs.

ds4 예시

{
  models: {
    providers: {
      ds4: {
        baseUrl: "http://127.0.0.1:18000/v1",
        apiKey: "ds4-local",
        api: "openai-completions",
        timeoutSeconds: 300,
        localService: {
          command: "<DS4_DIR>/ds4-server",
          args: [
            "--model",
            "<DS4_DIR>/ds4flash.gguf",
            "--host",
            "127.0.0.1",
            "--port",
            "18000",
            "--ctx",
            "32768",
            "--tokens",
            "128",
          ],
          cwd: "<DS4_DIR>",
          healthUrl: "http://127.0.0.1:18000/v1/models",
          readyTimeoutMs: 300000,
          idleStopMs: 0,
        },
        models: [],
      },
    },
  },
}

전체 설정, 컨텍스트 크기 조정 및 검증 명령: ds4.

로컬 모델

로컬 모델 설정, 공급자 선택 및 안전 지침입니다.

Inferrs

inferrs OpenAI 호환 로컬 서버를 통해 OpenClaw를 실행합니다.

Gateway

Remote access

Security

Nodes and media

Web interfaces

로컬 모델 서비스

작동 방식

구성 형태

필드

Inferrs 예시

ds4 예시

관련 항목

로컬 모델

Inferrs

​작동 방식

​구성 형태

​필드

​Inferrs 예시

​ds4 예시

​관련 항목

로컬 모델

Inferrs

작동 방식

구성 형태

필드

Inferrs 예시

ds4 예시

관련 항목