OpenClaw 컨텍스트 16k 문제 해결 방법

OpenClaw 컨텍스트 16k 문제 해결 방법

OpenClaw의 모델 컨텍스트 크기는 16k로 고정되지 않으며 로컬 설정에 따라 결정됩니다. ~/.openclaw/openclaw.json 또는 ~/.openclaw/agents/<agentId>/agent/models.json을 확인하여 해당 모델의 contextWindow와 maxTokens를 실제 지원 값으로 변경하십시오. MiniMax-M2.5의 경우 contextWindow: 196608, maxTokens: 8192로 변경할 수 있습니다. 수정 후 OpenClaw를 재시작하면 됩니다. 공식 설정 참고 자료와 MiniMax 예시도 이 작성 방식을 지원합니다.

이 상황의 본질적인 원인은 사용자 지정 provider / 사용자 지정 모델의 contextWindow를 16000 또는 그보다 낮게 설정한 것입니다. OpenClaw의 실제 컨텍스트는 설정에 크게 좌우되므로 모델이 더 큰 컨텍스트를 실제로 지원한다면 값을 늘려야 합니다. 그렇지 않으면 API rate limit reached, 컨텍스트 부족 또는 긴 대화의 비정상 동작과 같은 문제가 쉽게 발생합니다. 공식 설정 참고 자료에는 OpenClaw의 기본 설정 파일이 ~/.openclaw/openclaw.json이며 agent 디렉터리에 models.json을 별도로 둘 수도 있다고 명시되어 있습니다. 또한 모델을 일치시킬 때 contextWindow / maxTokens는 명시적 설정과 암시적 catalog 중 더 높은 값을 사용합니다.

OpenClaw 설정 페이지의 ‘Settings’ 탭입니다. 왼쪽의 여러 탭 중 ‘Settings’가 빨간색 테두리로 강조되어 있…

OpenClaw 컨텍스트 설정 수정 안내

1. 문제 현상

OpenClaw에서 사용자 지정 모델 또는 타사 중계 모델을 연동할 때 모델 설정의 컨텍스트 창이 다음과 같이 너무 작으면 문제가 발생할 수 있습니다.

"contextWindow": 16000,
"maxTokens": 4096

다음과 같은 문제가 나타날 수 있습니다.

• 긴 대화가 쉽게 실패합니다.
• 도구 호출 시 오류가 더 자주 발생합니다.
• 페이지에 API rate limit reached가 표시됩니다.
• 모델이 더 큰 컨텍스트를 지원하더라도 OpenClaw가 계속 작은 값으로 처리합니다.

OpenClaw 공식 문서에 따르면 모델의 contextWindow와 maxTokens는 설정에서 명시적으로 지정할 수 있습니다. 기본 설정 파일 경로는 ~/.openclaw/openclaw.json이며 agent 디렉터리의 models.json을 사용하여 별도로 재정의할 수도 있습니다.

2. 설정 파일 위치

1) 기본 설정 파일 경로

OpenClaw의 기본 설정 파일은 다음과 같습니다.

~/.openclaw/openclaw.json

공식 문서에도 명시되어 있습니다.

2) Agent 모델 설정 경로

agent별로 모델을 설정하는 경우 일반적인 경로는 다음과 같습니다.

~/.openclaw/agents/<agentId>/agent/models.json

공식 문서에 따르면 사용자 지정 provider는 models.providers에 추가하거나 ~/.openclaw/agents/<agentId>/agent/models.json에 작성할 수 있습니다.

3) 사용자 지정 Agent 루트 디렉터리를 변경한 경우

다음 환경 변수를 설정했다면

OPENCLAW_AGENT_DIR

agent 설정 디렉터리가 이 환경 변수로 재정의됩니다. 공식 문서에서도 OPENCLAW_AGENT_DIR 또는 PI_CODING_AGENT_DIR을 통해 agent 설정 루트 디렉터리를 변경할 수 있다고 설명합니다.

3. 수정 방법

방법 A: 기본 설정 수정

openclaw.json

다음 파일을 엽니다.

~/.openclaw/openclaw.json

현재 모델 제공자에 해당하는 설정을 찾습니다. 예:

{
  models: {
    mode: "merge",
    providers: {
      minimax: {
        baseUrl: "https://api.minimax.io/anthropic",
        api: "anthropic-messages",
        apiKey: "你的 API Key",
        models: [
          {
            id: "MiniMax-M2.5",
            name: "MiniMax-M2.5",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192
          }
        ]
      }
    }
  }
}

공식 MiniMax 예시에 제시된 MiniMax-M2.5 설정도 contextWindow: 196608, maxTokens: 8192입니다.

방법 B: agent 아래의 파일 수정

models.json

다음 파일을 엽니다.

~/.openclaw/agents/<agentId>/agent/models.json

해당 모델의 다음 값을

"contextWindow": 16000,
"maxTokens": 4096

다음과 같이 더 적절한 값으로 변경합니다.

"contextWindow": 196608,
"maxTokens": 8192

4. 권장 입력값

값을 임의로 입력하지 마십시오. ‘1M 컨텍스트를 원하므로 1000000을 입력하겠다’고 해서 그대로 동작하지는 않습니다.

권장 원칙

• contextWindow: 모델이 실제 지원하는 값 입력
• maxTokens: 모델의 실제 최대 출력 값 입력
• 중계 플랫폼을 사용하는 경우 원본 제조사의 홍보 값만 보지 말고 중계 플랫폼이 실제 허용하는 상한 확인

MiniMax-M2.5 예시

OpenClaw 공식 예시의 권장값은 다음과 같습니다.

"contextWindow": 196608,
"maxTokens": 8192

5. 수정 후 수행할 작업

설정을 저장한 뒤 OpenClaw 또는 해당 gateway 프로세스를 재시작합니다.

자주 사용하는 명령은 다음과 같습니다.

openclaw models list
openclaw models set minimax/MiniMax-M2.5

공식 문서에서도 모델 확인 및 전환에 이 두 명령을 사용합니다.

서비스 방식으로 실행 중이라면 다음과 같이 해당 서비스도 재시작해야 합니다.

openclaw gateway restart

또는 사용 중인 systemd / pm2 / docker 컨테이너를 재시작합니다.

6. 추가 설명

OpenClaw 공식 설정 참고 자료에는 다음 내용도 있습니다.

• 사용자 지정 provider를 models.providers에 직접 작성할 수 있습니다.
• contextWindow / maxTokens를 명시적으로 설정할 수 있습니다.
• 일치하는 모델을 찾을 때 명시적 설정과 암시적 catalog 중 더 높은 값을 사용합니다.
• 자체 설정으로 models.json을 완전히 덮어쓰려면 models.mode: "replace"를 사용할 수 있습니다.

또한 현재 공식 문서에는 custom providers에서 이 필드를 생략하면 기본값으로 contextWindow: 200000, maxTokens: 8192가 설정된다고 설명되어 있습니다. 따라서 고객 환경에서 여전히 16k 또는 4k로 표시된다면 ‘OpenClaw의 현재 기본값이 16k’인 것이 아니라 로컬 모델 설정의 값이 수동으로 작게 입력되었거나 기존 설정이 남아 있는 경우일 가능성이 큽니다.