OpenClaw는 오픈소스 AI 에이전트 도구로, AI 에이전트를 구성하고 관리하는 데 사용됩니다. 하지만 실제 사용 중 시작 실패나 프록시 연결 오류가 자주 발생합니다. 이 글에서는 가장 흔한 오류 코드와 원인을 정리하고, 검증된 수정 단계를 제공하여 OpenClaw를 신속하게 정상 작동 상태로 되돌릴 수 있도록 도와드립니다.
시작 실패: 설정 파일 오류와 의존성 누락
OpenClaw 시작 시 "config.json parse error" 또는 "missing required field" 오류가 발생한다면, 일반적으로 설정 파일 형식이 잘못되었거나 필수 매개변수가 누락된 경우입니다. config.json에 api_key, model_endpoint, proxy_mode와 같은 필수 항목이 포함되어 있는지 확인하고, JSON 검증 도구를 사용하여 불필요한 쉼표나 따옴표 불일치가 없는지 점검하세요. "dependency not found" 오류가 발생하면 필요한 Python 패키지가 설치되지 않은 것이므로 pip install -r requirements.txt를 실행하여 해결할 수 있습니다.
일부 Windows 사용자는 "permission denied" 오류를 경험하기도 하는데, 이는 OpenClaw가 시스템 프록시 설정을 읽어야 하기 때문입니다. 관리자 권한으로 터미널을 실행하거나, 백신 소프트웨어가 포트 수신 권한을 차단하고 있는지 확인하세요.
프록시 연결 이상: 포트 점유 및 네트워크 프록시 충돌
OpenClaw에서 "port already in use" 오류가 발생하면 기본 포트(예: 8080)가 다른 프로그램에 의해 사용 중인 것입니다. lsof -i :8080(Linux/macOS) 또는 netstat -ano | findstr 8080(Windows) 명령어로 점유 중인 프로세스를 찾아 종료하거나, 시작 명령에 --port 8081을 추가하여 포트를 변경하세요. "connection refused" 오류가 나타나면 대상 AI 서비스의 주소와 포트가 올바르게 입력되었는지 확인하고, 로컬 방화벽에서 해당 포트를 허용하고 있는지 점검하세요.
시스템 수준 프록시를 사용하여 인터넷에 접속하는 사용자의 경우, OpenClaw가 내부 네트워크와 외부 네트워크 트래픽을 올바르게 분리하지 못할 수 있습니다. config.json에서 proxy_mode를 exclusive 또는 direct로 설정하여 프록시 중첩을 방지하는 것이 좋습니다.