openclaw doctor로 게이트웨이 상태 점검하기

분명히 설정을 다 마쳤는데 Gateway가 제대로 작동하지 않아 답답한 적 있으신가요? 어디서부터 손을 대야 할지 막막할 때, 하나하나 수동으로 점검하는 대신 더 효율적인 방법을 추천할게요.

설정 파일의 오타나 환경 변수 충돌처럼 사소하지만 찾기 어려운 문제들을 빠르게 잡아내야 개발 흐름이 끊기지 않아요. 이럴 때 openclaw doctor를 사용하면 시스템 상태를 진단하고 즉시 수정할 수 있습니다.

필요한 것

• OpenClaw CLI
• 운영 중인 Gateway 및 Channel

빠른 시작

5분 안에 Gateway의 상태를 점검하고 문제를 해결하는 방법이에요. 아래 명령어 중 상황에 맞는 것을 터미널에 입력해 보세요.

# 기본적인 상태 점검 실행
openclaw doctor

# 문제 발견 시 자동으로 복구 시도
openclaw doctor --repair

# 더 깊은 단계까지 상세 점검 수행
openclaw doctor --deep

# 자동 복구 실행 (repair와 동일)
openclaw doctor --fix

--fix (또는 --repair) 옵션을 사용하면 기존 설정은 ~/.openclaw/openclaw.json.bak에 자동으로 백업돼요. 그 후 알 수 없는 설정 키를 제거하고 정리된 내용을 리스트로 보여줍니다.

문제 해결

점검 과정에서 흔히 발생할 수 있는 상황과 해결 방법이에요.

1. 대화형 프롬프트가 나타나지 않는 경우

Keychain이나 OAuth 수정 같은 대화형 프롬프트는 stdin이 TTY이고 --non-interactive 옵션이 설정되지 않았을 때만 작동해요. cron, Telegram, 또는 터미널이 없는 Headless 환경에서 실행하면 프롬프트 단계는 자동으로 건너뛰게 됩니다.

2. macOS에서 발생하는 인증 오류

macOS에서 launchctl을 통해 환경 변수를 설정했다면, 설정 파일보다 이 값이 우선순위를 가져요. 이로 인해 지속적인 “unauthorized” 에러가 발생할 수 있습니다. 아래 명령어로 환경 변수를 확인하고 해제해 보세요.

# 환경 변수 확인
launchctl getenv OPENCLAW_GATEWAY_TOKEN
launchctl getenv OPENCLAW_GATEWAY_PASSWORD

# 환경 변수 해제
launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD

문제가 계속 해결되지 않는다면 AI Setup Assistant에 질문해 주세요.

다음 단계

• Troubleshooting 가이드
• Security 보안 감사