OpenClaw gateway.mode missing 오류 완전 수정 2026: config validate 실패·dual-auth 충돌 해결 가이드
AI 대형 모델 활용 가이드
OpenClaw와 함께 사용할 최적의 로컬 LLM을 찾고 있나요? AI 대형 모델 가이드 →
이 글에서 다루는 내용: OpenClaw를 깨끗이 재설치하거나 업데이트한 후 Gateway start blocked: set gateway.mode=local 오류와 config validate: gateway.auth.mode unset 오류, 그리고 토큰·비밀번호 dual-auth 충돌로 게이트웨이가 시작되지 않는 세 가지 설정 파일 오류를 완전히 해결하는 방법을 단계별로 설명합니다. GitHub Issues #10767, Discussion #40368에서 확인된 실제 버그입니다.
오류 유형 1
gateway.mode missing (clean install)
재설치 후 gateway.mode 필드가 openclaw.json에 없음
오류 유형 2
gateway.auth.mode unset (dual-auth)
토큰과 비밀번호 두 가지 인증이 동시에 있어 충돌
오류 유형 3
config validate: schema mismatch
업데이트 후 스키마 변경으로 기존 설정 파일 불일치
오류 유형 1: gateway.mode missing (깨끗한 설치 후)
OpenClaw를 완전히 삭제(rm -rf ~/.openclaw)하고 재설치한 뒤 게이트웨이를 시작하려 하면 다음 오류가 발생합니다:
# GitHub Issue #10767 - macOS에서 발생하는 오류 메시지
Error: Gateway start blocked
Reason: gateway.mode is unset (current value: undefined)
Expected: set gateway.mode=local OR gateway.mode=remote
Fix: openclaw config set gateway.mode local
# or for remote: openclaw config set gateway.mode remote
이 오류가 발생하는 이유는 OpenClaw 설치 후 onboard 마법사가 gateway.mode 필드를 초기화하지 않는 버그 때문입니다. 이전에는 기본값이 자동 설정됐지만, 특정 버전에서 이 초기화 단계가 빠졌습니다.
해결법 (30초)
# 방법 1: CLI 명령어로 직접 설정 (가장 빠름)
openclaw config set gateway.mode local
# 설정 확인
openclaw config get gateway.mode
# 출력: local
# 게이트웨이 재시작
openclaw gateway start
openclaw gateway status
# "gateway.mode: local ✅" 확인
# 방법 2: openclaw.json 직접 편집
nano ~/.openclaw/openclaw.json
# gateway 섹션에 mode 필드 추가:
{
"gateway": {
"mode": "local", ← 이 줄 추가
"auth": {
...
}
}
}
# 저장 후 검증
python3 -m json.tool ~/.openclaw/openclaw.json
openclaw config validate
💡 local vs remote 차이
gateway.mode: "local"
게이트웨이가 현재 컴퓨터에서 실행됨. 대부분의 사용자에게 해당. 기본값으로 설정 권장.
gateway.mode: "remote"
게이트웨이가 다른 서버(VPS 등)에서 실행 중. 원격 서버 배포 또는 Raspberry Pi 설정 시 사용.
오류 유형 2: gateway.auth.mode unset (dual-auth 충돌)
OpenClaw 설정 파일에 gateway.auth.token과 gateway.auth.password가 동시에 존재하는데 어떤 방식을 사용할지 명시되지 않으면 발생합니다:
# Discussion #40368 - dual-auth 충돌 오류 (2026.3.7 버전)
Error: config validate failed
gateway.auth.mode is not set
Both gateway.auth.token and gateway.auth.password are present
Ambiguous: cannot determine which authentication method to use
Fix: Add "mode": "token" or "mode": "password" to gateway.auth block
이 오류는 주로 다음 상황에서 발생합니다:
- OpenClaw를 토큰 방식으로 처음 설치 후, 비밀번호 방식을 추가로 설정했을 때
- 다중 플랫폼(macOS + Linux)에서 설정 파일을 동기화했을 때
- 2026.3.7 버전 업데이트 후 기존 설정 파일에 mode 필드가 추가되지 않았을 때
해결법: gateway.auth.mode 명시적 설정
# 현재 auth 설정 확인
cat ~/.openclaw/openclaw.json | python3 -c \
"import sys,json; d=json.load(sys.stdin); print(d.get('gateway',{}).get('auth',{}))"
토큰 방식 사용 시
# CLI로 설정
openclaw config set gateway.auth.mode token
# 또는 openclaw.json 편집
"auth": {
"mode": "token", ← 추가
"token": "your-token",
"password": "old-pw" ← 삭제 권장
}
비밀번호 방식 사용 시
# CLI로 설정
openclaw config set gateway.auth.mode password
# 또는 openclaw.json 편집
"auth": {
"mode": "password", ← 추가
"token": "old-token", ← 삭제 권장
"password": "your-pw"
}
⚠️ 사용하지 않는 인증 필드 삭제 권장
mode를 설정해도 사용하지 않는 인증 필드(토큰 방식 사용 시 password, 비밀번호 방식 사용 시 token)가 남아있으면 향후 업데이트에서 다시 충돌이 발생할 수 있습니다. 사용하지 않는 필드는 삭제하는 것이 좋습니다. 삭제 전 반드시 백업: cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
오류 유형 3: config validate schema mismatch (업데이트 후)
OpenClaw 버전 업데이트 후 설정 파일 스키마가 변경되면 기존 openclaw.json이 새 스키마와 맞지 않아 config validate가 실패합니다:
# 업데이트 후 발생하는 스키마 불일치 오류
openclaw config validate
❌ config validation failed (3 errors):
1. gateway.mode: required field missing (added in v2026.3.7)
2. providers.fallback.timeout: deprecated, use providers.fallback.timeout_per_provider
3. heartbeat.delivery: unknown field (removed in v2026.2.1)
이런 경우 오류를 하나씩 수동으로 수정하거나, openclaw doctor --fix로 자동 수정을 시도할 수 있습니다.
자동 수정 시도
openclaw doctor --fix
# 성공 시: "Fixed 3 config issues" 메시지
# 실패 시: 수동 수정 필요 (아래 참조)
대부분의 deprecated 필드와 누락된 필드를 자동으로 처리합니다. 단, 민감한 인증 관련 항목은 수동 확인 후 처리.
수동 수정: 누락된 필드 추가
# 누락된 필드 하나씩 추가
openclaw config set gateway.mode local
openclaw config set providers.fallback.timeout_per_provider 30
# 설정 후 검증
openclaw config validate
# ✅ config validation passed
수동 수정: 구식 필드 제거
# 구식 필드 제거
openclaw config unset providers.fallback.timeout
openclaw config unset heartbeat.delivery
# 최종 검증
openclaw config validate && openclaw doctor
올바른 openclaw.json gateway 섹션 완전 템플릿
모든 필드가 올바르게 설정된 gateway 섹션 템플릿입니다. 자신의 환경에 맞게 값을 수정하세요.
# 완전한 gateway 섹션 템플릿 (2026.3.7+ 기준)
{
"gateway": {
"mode": "local", // ✅ 필수: local 또는 remote
"port": 51000, // 기본 포트 (변경 가능)
"auth": {
"mode": "token", // ✅ 필수: token 또는 password
"token": "your-token-here" // mode=token 시 사용
// "password": "..." ← mode=password 시 여기 대신 사용
},
"log": {
"level": "info" // debug, info, warn, error
}
}
}
어떤 오류든 해결하는 통합 수정 절차
어떤 유형의 config 오류가 발생했든, 아래 순서로 진행하면 99%의 경우 해결됩니다.
현재 설정 백업
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d)오류 내용 확인
openclaw config validate 2>&1자동 수정 시도
openclaw doctor --fix남은 오류 수동 수정 (필요 시)
openclaw config set gateway.mode local
openclaw config set gateway.auth.mode token검증 재실행
openclaw config validate"✅ config validation passed" 확인
게이트웨이 재시작
openclaw gateway restart전체 상태 최종 확인
openclaw doctor
openclaw gateway status
# 모든 항목 ✅ 확인자주 묻는 질문
Q. openclaw doctor --fix를 실행했는데 오류가 그대로입니다.
doctor --fix가 자동 수정하지 못하는 오류가 있습니다. 특히 gateway.auth.mode처럼 판단이 필요한 필드(토큰/비밀번호 중 어느 것을 사용할지 모르므로)는 수동으로 설정해야 합니다. 오류 메시지를 정확히 읽고 이 글의 해당 섹션을 참고하세요.
Q. openclaw.json을 편집했는데 JSON 파싱 오류가 납니다.
JSON 형식 오류가 있으면 OpenClaw가 아예 시작되지 않습니다. 편집 후 반드시 python3 -m json.tool ~/.openclaw/openclaw.json으로 유효성을 확인하세요. 오류가 있다면 백업 파일(openclaw.json.bak)을 복원하세요.
Q. 업데이트 전에 이런 오류가 없었는데 업데이트 후 갑자기 발생합니다.
2026.3.7 업데이트에서 gateway.mode와 gateway.auth.mode 필드가 명시적 필수 항목으로 바뀌었습니다. 이전 버전에서는 이 필드가 없어도 기본값이 적용됐지만, 새 버전에서는 명시적으로 설정해야 합니다. 업데이트 후 openclaw config validate를 습관적으로 실행하세요.
Q. config validate가 통과했는데 게이트웨이가 여전히 시작되지 않습니다.
config는 정상이지만 게이트웨이 포트가 이미 사용 중인 경우입니다. lsof -i :51000으로 포트 사용 여부를 확인하고, 충돌하는 프로세스를 종료하세요. 또는 openclaw config set gateway.port 51001로 포트를 변경해보세요.
업데이트 전 설정 백업 자동화
config 오류의 대부분은 업데이트 후에 발생합니다. 업데이트 전 자동으로 백업하는 cron 작업을 설정해두면 문제 발생 시 빠르게 복원할 수 있습니다.
# OpenClaw에게 자동 백업 설정 요청 (Telegram에서)
"매일 오전 3시에 ~/.openclaw 폴더를 ~/openclaw-backups/에
날짜 이름으로 백업하는 cron 작업 만들어줘.
백업은 최신 7개만 유지해줘."
config 오류 수정 후 안정적인 운영 환경 만들기
gateway.mode와 config 오류를 해결했다면, 이제 OpenClaw가 안정적으로 작동할 환경을 갖추는 것이 중요합니다. 특히 게이트웨이는 24시간 계속 실행되면서 AI 모델 API 서버와 통신하므로, 네트워크 연결 품질이 안정적인 운영의 핵심입니다.
실제 OpenClaw 사용자들의 경험에 따르면, config 오류 해결 후에도 간헐적인 게이트웨이 재시작과 연결 끊김을 경험하는 경우가 있습니다. 이 중 상당수는 설정 문제가 아닌 불안정한 해외 API 서버 연결이 원인입니다. 특히 API 서버와 게이트웨이 간 WebSocket 연결이 자주 끊기면 gateway.mode가 올바르게 설정돼도 예기치 않은 재시작이 발생합니다.
OpenClaw 게이트웨이 안정 운영을 위한 VPN 추천 순위
VPN07 — 게이트웨이 24시간 안정 운영
10년 이상 운영된 글로벌 VPN. 1000Mbps 기가급 대역폭으로 OpenClaw 게이트웨이와 AI API 서버 간 WebSocket 연결을 24시간 안정적으로 유지합니다.
🥈 2위 — 일반 VPN A
6.8/10속도 불안정, AI API 전용 경로 없음. 게이트웨이 장시간 운영 시 간헐적 연결 끊김 발생.
🥉 3위 — 일반 VPN B
6.3/10월 비용 높음, WebSocket 연결 유지가 약해 게이트웨이 재시작이 잦음.
VPN07 — config 수정 후 완벽한 운영 환경
1000Mbps로 게이트웨이 24시간 안정 운영 보장
10년 이상 안정 운영. gateway.mode를 올바르게 설정한 후에는 VPN07의 1000Mbps 기가급 네트워크로 AI API 서버와의 WebSocket 연결을 24시간 안정적으로 유지해 예기치 않은 게이트웨이 재시작을 방지합니다. 70개국 서버에서 최적 경로를 자동 선택합니다.
AI 대형 모델 활용 가이드
외부 API 의존 없이 로컬에서 실행하는 LLM으로 gateway 오류 걱정 없이 OpenClaw를 운영하세요. AI 대형 모델 가이드 →