OpenClaw 모델 설정 가이드: 최적의 AI 모델 선택 및 변경

새로운 프로젝트를 시작할 때마다 어떤 LLM을 쓸지 고민하는 건 모든 개발자의 공통된 고민이죠. API 키를 일일이 설정하고 긴 모델 이름을 매번 입력하는 것도 꽤 번거로운 일이에요.

OpenClaw에서는 이런 번거로움을 줄이고 모델 선택과 관리를 아주 유연하게 할 수 있어요. 상황에 맞는 최적의 모델을 어떻게 설정하고 활용하는지 하나씩 살펴볼게요.

Model Selection & Aliases

OpenClaw에서 모델을 선택하고 설정하는 방법을 알아봅니다.

---

”기본 모델”이란 무엇인가요?

OpenClaw의 기본 모델은 여러분이 아래 설정값에 지정한 모델을 의미해요.

agents.defaults.model.primary

모델은 provider/model 형식으로 참조합니다 (예: anthropic/claude-opus-4-5).

---

어떤 모델을 추천하시나요?

• 추천 기본 모델: anthropic/claude-opus-4-5
• 괜찮은 대안: anthropic/claude-sonnet-4-5
• 신뢰할 수 있는 모델 (개성은 적음): openai/gpt-5.2
• 가성비 모델: zai/glm-4.7

기본적인 원칙은 이래요. 결과가 중요한 작업에는 비용이 들더라도 가장 좋은 모델을 쓰고, 일상적인 대화나 요약에는 저렴한 모델을 사용하세요.

⚠️ 강력 경고: 성능이 낮거나 과하게 양자화(quantized)된 모델은 prompt injection과 안전하지 않은 동작에 더 취약할 수 있습니다.

---

로컬 모델(llama.cpp, vLLM, Ollama)도 사용할 수 있나요?

네, 가능해요. 로컬 서버가 OpenAI 호환 API를 제공한다면 custom provider로 연결할 수 있습니다. Ollama는 직접 지원되므로 가장 간편하게 시작할 수 있는 방법이에요.

보안 참고: 크기가 작거나 양자화가 많이 된 모델은 prompt injection에 취약합니다. Tool을 사용하는 봇이라면 대형 모델을 사용하시길 강력히 권장드려요.

---

설정 파일을 초기화하지 않고 모델을 바꾸려면 어떻게 하나요?

안전한 방법들:

• 채팅창에서 /model 입력 (세션별 빠른 변경)
• openclaw models set ... 실행 (모델 설정만 업데이트)
• openclaw configure --section models 실행 (대화형 설정)
• ~/.openclaw/openclaw.json 파일의 agents.defaults.model 직접 수정

전체 설정을 덮어쓰려는 의도가 아니라면, 일부 객체만 있는 config.apply 사용은 피하는 게 좋아요.

---

재시작 없이 즉시 모델을 바꾸는 방법은?

채팅 중에 /model 명령어를 단독 메시지로 보내보세요.

/model sonnet
/model haiku
/model opus
/model gpt
/model gpt-mini
/model gemini
/model gemini-flash

/model, /model list, 또는 /model status 명령어로 사용 가능한 모델 목록을 확인할 수 있습니다.

번호로 선택할 수도 있어요.

/model 3

특정 인증 프로필을 강제로 지정하는 것도 가능합니다.

/model opus@anthropic:default
/model opus@anthropic:work

---

일상 업무에는 GPT 5.2를, 코딩에는 Codex 5.2를 따로 쓸 수 있나요?

네, 당연히 가능하죠.

방법 A: 세션마다 전환하기 하나를 기본으로 두고 필요할 때마다 바꿔주세요.

/model gpt-5.2      # for daily tasks
/model gpt-5.2-codex  # for coding

방법 B: sub-agents 활용 코딩 작업은 다른 기본 모델이 설정된 sub-agents에게 맡기도록 경로를 설정할 수 있습니다.

---

왜 “Model … is not allowed”라는 메시지가 뜨고 응답이 없나요?

agents.defaults.models가 설정되어 있다면, 이 목록이 /model 명령어와 세션 오버라이드에 적용되는 allowlist(허용 목록) 역할을 하게 됩니다. 목록에 없는 모델을 선택하면 에러가 발생해요.

해결 방법: 해당 모델을 agents.defaults.models에 추가하거나, allowlist 설정을 제거하거나, /model list에 있는 모델 중 하나를 선택하세요.

---

왜 “Unknown model: minimax/MiniMax-M2.1”이라는 오류가 뜨나요?

이건 Provider가 설정되지 않았다는 뜻이에요 (MiniMax provider 설정이나 인증 프로필을 찾을 수 없는 경우입니다).

체크리스트:

1. MiniMax가 설정되었는지 확인하세요 (마법사 도구 또는 JSON)
2. 대소문자를 구분해서 정확한 모델 ID를 사용했는지 확인하세요: minimax/MiniMax-M2.1
3. openclaw models list를 실행하고 목록에서 선택하세요.

---

opus / sonnet / gpt 같은 단축어가 내장되어 있나요?

네, OpenClaw는 몇 가지 기본 단축어(shorthands)를 제공해요.

• opus → anthropic/claude-opus-4-5
• sonnet → anthropic/claude-sonnet-4-5
• gpt → openai/gpt-5.2
• gpt-mini → openai/gpt-5-mini
• gemini → google/gemini-3-pro-preview
• gemini-flash → google/gemini-3-flash-preview

만약 같은 이름으로 직접 alias를 설정한다면, 여러분이 설정한 값이 우선권을 가집니다.

---

모델 단축어(alias)를 직접 정의하거나 수정하려면 어떻게 하나요?

Alias는 agents.defaults.models.<modelId>.alias 설정에서 가져옵니다.

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-5" },
      models: {
        "anthropic/claude-opus-4-5": { alias: "opus" },
        "anthropic/claude-sonnet-4-5": { alias: "sonnet" },
        "anthropic/claude-haiku-4-5": { alias: "haiku" }
      }
    }
  }
}

---

OpenRouter나 Z.AI 같은 다른 Provider의 모델은 어떻게 추가하나요?

OpenRouter:

{
  agents: {
    defaults: {
      model: { primary: "openrouter/anthropic/claude-sonnet-4-5" },
      models: { "openrouter/anthropic/claude-sonnet-4-5": {} }
    }
  },
  env: { OPENROUTER_API_KEY: "sk-or-..." }
}

Z.AI:

{
  agents: {
    defaults: {
      model: { primary: "zai/glm-4.7" },
      models: { "zai/glm-4.7": {} }
    }
  },
  env: { ZAI_API_KEY: "..." }
}

도움이 필요하신가요? AI Setup Assistant에게 물어보세요.

다음 단계

• Providers 설정 가이드
• Custom Agents 만들기