OpenClaw의 엄격한 설정 검증과 Doctor 활용하기

설정 파일은 조금만 관리가 소홀해져도 금방 복잡해지곤 해요. 오타 하나 때문에 기능이 작동하지 않거나, 더 이상 사용하지 않는 오래된 설정 값이 남아있어 디버깅을 어렵게 만들 때가 많죠. 특히 어떤 설정이 유효한지 명확하지 않으면 운영 환경에서 예상치 못한 문제가 발생할 수 있습니다.

이런 문제를 해결하기 위해 OpenClaw는 매우 엄격한 설정 검증 방식을 도입했어요. 이제 잘못된 설정이 있다면 시스템이 조용히 무시하는 대신, 즉시 문제를 알려주고 해결 방법을 제시합니다.

필요한 것

시작하기 전에 다음 사항을 확인해 주세요.

• openclaw.plugin.json 파일이 포함된 Plugin (모든 Plugin에는 Manifest가 필수예요)
• Zod Schema를 준수하는 설정 파일
• 최신 버전의 OpenClaw CLI

빠른 시작

설정 오류를 5분 안에 해결하고 Gateway를 실행하는 방법입니다.

1. 설정 상태 확인하기 OpenClaw를 실행하면 자동으로 doctor (dry-run)이 동작해요. 수동으로 확인하려면 다음 명령어를 입력하세요.

   openclaw doctor

2. 자동 수정 적용하기 알 수 없는 키가 있거나 Migration이 필요한 경우 다음 명령어로 한 번에 해결할 수 있어요.

   openclaw doctor --fix

3. 서비스 실행 설정이 정상이면 모든 명령어를 평소처럼 사용할 수 있습니다.

엄격한 검증 규칙

OpenClaw는 설정 파일의 모든 레벨에서 Schema와 정확히 일치하는지 검사해요.

• 알 수 없는 키 거부: Root는 물론 중첩된 구조 어디에서도 정의되지 않은 키는 허용되지 않아요.
• Plugin Schema 필수: 모든 Plugin은 openclaw.plugin.json 안에 JSON Schema를 포함해야 합니다. Schema가 없는 Plugin은 로드되지 않아요.
• 자동 Migration 중단: 이전에는 실행 시 자동으로 설정을 변경해 주었지만, 이제는 doctor 명령어를 통해서만 Migration이 진행됩니다.
• Startup 검사: Gateway가 시작될 때 설정을 검증하며, 유효하지 않으면 진단용 명령어를 제외한 모든 동작이 차단돼요.

설정 오류 시 허용되는 명령어

설정이 올바르지 않으면 OpenClaw는 “Config invalid. Run openclaw doctor --fix.”라는 메시지와 함께 실행을 멈춰요. 이때는 오직 다음 진단 명령어만 사용할 수 있습니다.

• openclaw doctor 및 openclaw logs
• openclaw health 및 openclaw help
• openclaw status 및 openclaw gateway status

문제 해결

설정 과정에서 마주칠 수 있는 일반적인 문제입니다.

Plugin이 로드되지 않아요

• Plugin Manifest(openclaw.plugin.json)에 Schema가 포함되어 있는지 확인하세요.
• Plugin 설정값이 해당 Schema와 일치하는지 openclaw doctor로 확인해 보세요.

알 수 없는 키(Unknown keys) 에러가 발생해요

• 설정 파일에 오타가 있거나, 더 이상 지원하지 않는 이전 버전의 설정이 남아있을 수 있어요.
• openclaw doctor --fix를 실행하면 유효하지 않은 키를 자동으로 제거하고 최신 상태로 업데이트해 줍니다.

---

더 자세한 도움이 필요하신가요? AI Setup Assistant에게 물어보세요!

다음 단계

• Plugin Manifest 작성 가이드
• CLI 명령어 레퍼런스