로컬 모델

​

최소 하드웨어

​

백엔드 선택

​

LM Studio + 대형 로컬 모델(Responses API)

{
  agents: {
    defaults: {
      model: { primary: "lmstudio/my-local-model" },
      models: {
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "lmstudio/my-local-model": { alias: "Local" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

• LM Studio 설치: https://lmstudio.ai
• 사용 가능한 가장 큰 모델 빌드를 다운로드하고(“small”/심하게 양자화된 변형은 피함) 서버를 시작한 다음, http://127.0.0.1:1234/v1/models에 해당 모델이 표시되는지 확인하세요.
• my-local-model을 LM Studio에 표시되는 실제 모델 ID로 바꾸세요.
• 모델을 로드된 상태로 유지하세요. 콜드 로드는 시작 지연 시간을 늘립니다.
• LM Studio 빌드의 값이 다르면 contextWindow/maxTokens를 조정하세요.
• WhatsApp에서는 최종 텍스트만 전송되도록 Responses API를 계속 사용하세요.
• 호스팅 모델을 폴백으로 계속 사용할 수 있도록 models.mode: "merge"를 유지하세요.

​

하이브리드 구성: 호스팅 기본 모델, 로컬 폴백

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["lmstudio/my-local-model", "anthropic/claude-opus-4-6"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "lmstudio/my-local-model": { alias: "Local" },
        "anthropic/claude-opus-4-6": { alias: "Opus" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

​

지역별 호스팅 / 데이터 라우팅

​

기타 OpenAI 호환 로컬 프록시

{
  agents: {
    defaults: {
      model: { primary: "local/my-local-model" },
    },
  },
  models: {
    mode: "merge",
    providers: {
      local: {
        baseUrl: "http://127.0.0.1:8000/v1",
        apiKey: "sk-local",
        api: "openai-completions",
        timeoutSeconds: 300,
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 120000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

• models.providers.mlx.models[].id: "mlx-community/Qwen3-30B-A3B-6bit"
• agents.defaults.model.primary: "mlx/mlx-community/Qwen3-30B-A3B-6bit"

• OpenClaw는 이를 네이티브 OpenAI 엔드포인트가 아니라 프록시 방식의 OpenAI 호환 경로로 취급합니다.
• 네이티브 OpenAI 전용 요청 형성은 적용되지 않습니다. 즉, service_tier, Responses store, OpenAI 추론 호환 페이로드 형성, 프롬프트 캐시 힌트가 없습니다.
• 숨겨진 OpenClaw 출처 헤더(originator, version, User-Agent)는 사용자 지정 프록시 URL에 삽입되지 않습니다.

• 문자열 전용 콘텐츠: 일부 서버는 구조화된 콘텐츠 부분 배열이 아니라 문자열 messages[].content만 허용합니다. models.providers.<provider>.models[].compat.requiresStringContent: true를 설정하세요.
• 엄격한 메시지 키: 서버가 role/content 외의 키가 포함된 메시지 항목을 거부하면 compat.strictMessageKeys: true를 설정하세요.
• 대괄호로 묶인 도구 텍스트: 일부 로컬 모델은 [tool_name] 뒤에 JSON과 [END_TOOL_REQUEST]가 오는 독립적인 대괄호 형식의 도구 요청을 텍스트로 출력합니다. OpenClaw는 이름이 해당 턴에 등록된 도구와 정확히 일치할 때만 이를 실제 도구 호출로 승격합니다. 그렇지 않으면 숨겨진 미지원 텍스트로 유지됩니다.
• 구조화되지 않은 도구 호출 형태의 텍스트: 모델이 도구 호출처럼 보이지만 구조화된 호출이 아닌 JSON/XML/ReAct 형식의 텍스트를 출력하면 OpenClaw는 이를 텍스트로 유지하고 실행 ID, 공급자/모델, 감지된 패턴 및 확인 가능한 경우 도구 이름과 함께 경고를 기록합니다. 이는 완료된 도구 실행이 아니라 공급자/모델 비호환성입니다.
• 도구 사용 강제: 도구가 어시스턴트 텍스트(원시 JSON/XML/ReAct 또는 빈 tool_calls 배열)로 표시되면 먼저 서버의 채팅 템플릿/파서가 도구 호출을 지원하는지 확인하세요. 도구 사용을 강제할 때만 파서가 작동한다면 모델별로 기본 프록시 값 tool_choice: "auto"를 재정의하세요.
  {
    agents: {
      defaults: {
        models: {
          "local/my-local-model": {
            params: {
              extra_body: {
                tool_choice: "required",
              },
            },
          },
        },
      },
    },
  }
  
  모든 일반 턴에서 도구를 호출해야 하는 경우에만 사용하세요. local/my-local-model을 openclaw models list에 표시되는 정확한 참조로 바꾸거나 CLI를 통해 설정하세요.
  openclaw config set agents.defaults.models '{"local/my-local-model":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge
  
• 추가 추론 강도: 사용자 지정 OpenAI 호환 모델이 기본 제공 프로필 이외의 OpenAI 추론 강도를 허용한다면 모델의 호환성 블록에 이를 선언하세요. "xhigh"를 추가하면 해당 모델 참조에서 /think xhigh, 세션 선택기, Gateway 유효성 검사 및 llm-task 유효성 검사에 노출됩니다.
  {
    models: {
      providers: {
        local: {
          baseUrl: "http://127.0.0.1:8000/v1",
          apiKey: "sk-local",
          api: "openai-responses",
          models: [
            {
              id: "gpt-5.4",
              name: "GPT 5.4 via local proxy",
              reasoning: true,
              input: ["text"],
              cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
              contextWindow: 196608,
              maxTokens: 8192,
              compat: {
                supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],
                reasoningEffortMap: { xhigh: "xhigh" },
              },
            },
          ],
        },
      },
    },
  }
  

​

더 작거나 엄격한 백엔드

1. 로컬 모델 응답 확인 - 도구와 에이전트 컨텍스트 없이:
   openclaw infer model run --local --model <provider/model> --prompt "Reply with exactly: pong" --json
   
2. Gateway 라우팅 확인 - 대화 기록, AGENTS 부트스트랩, 컨텍스트 엔진 조립, 도구 및 번들 MCP 서버는 건너뛰고 프롬프트만 전송하지만, Gateway 라우팅, 인증 및 제공자 선택은 계속 실행합니다.
   openclaw infer model run --gateway --model <provider/model> --prompt "Reply with exactly: pong" --json
   
3. 두 프로브는 모두 통과하지만 실제 에이전트 턴에서 잘못된 형식의 도구 호출이나 지나치게 큰 프롬프트로 인해 실패한다면 경량 모드를 사용해 보세요. agents.defaults.experimental.localModelLean: true로 설정합니다. 명시적으로 필요한 경우가 아니면 무거운 브라우저, Cron, 메시지, 미디어 생성, 음성 및 PDF 도구를 제외하고, exec는 직접 표시한 채 더 큰 도구 카탈로그를 기본적으로 구조화된 도구 검색 제어 뒤에 둡니다. 자세한 내용과 활성화 여부를 확인하는 방법은 실험적 기능 -> 로컬 모델 경량 모드를 참조하세요.
4. 최후의 수단으로 도구를 완전히 비활성화하려면 해당 모델에 models.providers.<provider>.models[].compat.supportsTools: false를 설정하세요. 그러면 에이전트가 도구 호출 없이 실행됩니다.
5. 그 이후의 병목은 업스트림에 있습니다. 경량 모드와 supportsTools: false를 적용한 후에도 더 큰 OpenClaw 실행에서만 백엔드가 계속 실패한다면, 남은 문제는 대개 OpenClaw의 전송 계층이 아니라 모델이나 서버 자체의 컨텍스트 창, GPU 메모리, kv-cache 축출 또는 백엔드 버그입니다.

​

문제 해결

• Gateway가 프록시에 연결할 수 없나요? curl http://127.0.0.1:1234/v1/models.
• LM Studio 모델이 언로드되었나요? 다시 로드하세요. 콜드 스타트는 흔한 “멈춤” 원인입니다.
• 로컬 서버에서 terminated, ECONNRESET이 표시되거나 턴 도중 스트림이 닫히나요? OpenClaw는 진단 정보에 낮은 카디널리티의 model.call.error.failureKind와 OpenClaw 프로세스의 RSS/힙 스냅샷을 기록합니다. LM Studio/Ollama의 메모리 압박이 원인이라면 해당 타임스탬프를 서버 로그 또는 macOS 충돌/jetsam 로그와 대조하여 모델 서버가 종료되었는지 확인하세요.
• 컨텍스트 오류가 발생하나요? OpenClaw는 감지된 모델 창 또는 agents.defaults.contextTokens가 이를 낮춘 경우 제한된 창을 기준으로 컨텍스트 창 사전 점검 임계값을 산출합니다. 8k를 최저값으로 하여 20% 미만일 때 경고하고, 4k를 최저값으로 하여 10% 미만일 때 강제로 차단합니다. 이 값은 유효 컨텍스트 창으로 제한되므로 과도하게 큰 모델 메타데이터가 유효한 사용자 제한을 거부하지 않습니다. contextWindow를 낮추거나 서버/모델의 컨텍스트 제한을 높이세요.
• messages[].content ... expected a string 오류가 발생하나요? 해당 모델 항목에 compat.requiresStringContent: true를 추가하세요.
• validation.keys 오류 또는 “message entries only allow role and content”가 표시되나요? 해당 모델 항목에 compat.strictMessageKeys: true를 추가하세요.
• 직접 /v1/chat/completions를 호출하면 작동하지만 Gemma 또는 다른 로컬 모델에서 openclaw infer model run --local이 실패하나요? 먼저 제공자 URL, 모델 참조, 인증 표시 및 서버 로그를 확인하세요. model run은 에이전트 도구를 완전히 건너뜁니다. model run은 성공하지만 더 큰 에이전트 턴에서 실패한다면 localModelLean 또는 compat.supportsTools: false로 도구 범위를 줄이세요.
• 도구 호출이 원시 JSON/XML/ReAct 텍스트로 표시되거나 제공자가 빈 tool_calls 배열을 반환하나요? 어시스턴트 텍스트를 무조건 도구 실행으로 변환하는 프록시를 추가하지 말고, 먼저 서버의 채팅 템플릿/파서를 수정하세요. 도구 사용을 강제할 때만 모델이 작동한다면 위의 params.extra_body.tool_choice: "required" 재정의를 추가하고 매 턴마다 도구 호출이 예상되는 세션에만 해당 모델 항목을 사용하세요.
• 안전: 로컬 모델은 제공자 측 필터를 건너뜁니다. 프롬프트 인젝션의 영향 범위를 제한하려면 에이전트의 범위를 좁게 유지하고 Compaction을 활성화하세요.

​

관련 항목

• 구성 참조
• 모델 장애 조치