OpenClaw 모델 목록이 갑자기 줄어드는 현상 대응 - agents.defaults.models의 숨은 동작

문제의 현상

갑자기 디스코드나 텔레그램에서 '/model' 명령어를 실행하면 전체 모델 목록이 아니라, 내가 현재 쓰고 있는 fallback 목록의 모델들만 표시되는 현상이 발생했다.

원래는 아래 이미지처럼 OpenClaw에서 지원하는 모든 모델의 목록이 표시돼야 한다.

 

원인 발견

에이전트와의 몇 차례 문답 끝에 원인을 찾았다. 'openclaw.json'의 'agents.defaults.models' 키가 화이트리스트로 동작한다. 이 키가 존재하면, 거기 명시된 모델 ID만 허용되고 나머지는 전부 차단된다.

// openclaw.json — 문제가 되는 설정 예시
{
  "agents": {
    "defaults": {
      "models": {
        "google-gemini-cli/gemini-3.1-pro-preview": {}  // ← 이것만 있으면 나머지 전부 차단
      }
    }
  }
}

 

왜 모르는 사이에 이런 일이 발생하나?

주로 이런 상황에서 의도치 않게 생성된다.

1. 특정 모델에 params를 설정하려고 넣었을 때
2. '/model' 명령어나 세션 모델 오버라이드가 config에 잘못 저장될 때
3. 에이전트가 config를 편집하면서 실수로 넣을 때

이 키의 용도가 얼핏 보면 "모델별 파라미터 설정"처럼 보이기 때문에, 화이트리스트가 될 거라고 예상하기 어렵다.

 

진단 방법

config 파일(openclaw.json)을 편집기에서 열고 직접 확인해도 되지만 눈에 확 들어오지 않는다. 터미널을 열고 아래 명령으로 'agents.defaults.models' 키가 있는지 확인한다.

python3 -c "
import json
with open('/Users/YOUR_USER/.openclaw/openclaw.json') as f:
    c = json.load(f)
models = c.get('agents', {}).get('defaults', {}).get('models', 'NOT SET')
print('agents.defaults.models:', models)
"

아래와 같이 표시돼야 정상(해당 키 없음)이다.

agents.defaults.models: NOT SET

아니면 아예 'openclaw models list --all' 명령을 실행해서 전체 모델 카탈로그가 나오는지 확인하는 방법도 있다.

openclaw models list        # 현재 설정된 모델만 표시
openclaw models list --all  # 전체 모델 카탈로그 표시

'--all' 없이 실행했을 때 일부 모델만 나오고, '--all'을 붙여도 동일하면 화이트리스트가 활성화된(잘못된) 상태다.

 

해결 방법

'agents.defaults.models' 키를 삭제한다.

방법 1: Python으로 직접 삭제 (추천)

아래 코드를 그대로 사용해도 되고 에이전트에게 새로 작성해 달라고 해도 된다.

import json

config_path = '/Users/YOUR_USER/.openclaw/openclaw.json'

with open(config_path) as f:
    c = json.load(f)

defaults = c.get('agents', {}).get('defaults', {})
if 'models' in defaults:
    del defaults['models']
    with open(config_path, 'w') as f:
        json.dump(c, f, indent=2, ensure_ascii=False)
    print('삭제 완료')
else:
    print('키 없음')

방법 2: openclaw.json 직접 편집

'agents.defaults.models' 항목 전체를 찾아서 삭제한다.

// 이 부분을 통째로 삭제
"models": {
  "google-gemini-cli/gemini-3.1-pro-preview": {}
}

agents.defaults 하위에 있는 models를 잘 찾아야 한다.

키 삭제 후 게이트웨이 재시작

openclaw gateway restart

 

재발 방지

config 편집 시 주의사항

• 'agents.defaults.models' 키는 절대 단독 모델만 넣지 말 것
• 특정 모델에 params(예: 'maxTokens', 'context1m')를 설정하려면, 이 키 대신 다른 방식을 찾거나 전체 허용 모델을 다 명시할 것
• config 편집 후 '/model' 명령어로 모델 목록 정상 여부 확인

증상이 다시 나타날 때 체크리스트

1. '/model' 결과가 전체 목록인지 확인
2. 'agents.defaults.models' 키 존재 여부 확인
3. 있으면 삭제 → 재시작

참고 - 관련 설정 구조

OpenClaw의 모델 허용 방식

설정	동작
'agents.defaults.models' 키 없음	OpenClaw 지원 모든 모델 허용
'agents.defaults.models' 키 있음	거기 명시된 모델만 허용 (화이트리스트)

모델별 파라미터 설정은 'models.providers' 아래에서 하는 게 안전하다.

// 안전한 방법: models.providers 아래 커스텀 모델 등록
{
  "models": {
    "providers": {
      "groq": {
        "baseUrl": "https://api.groq.com/openai/v1",
        "models": [
          { "id": "kimi-k2-instruct", "maxTokens": 16384, ... }
        ]
      }
    }
  }
}

끝.