OpenClaw & Moltbook FAQ

OpenClaw는 여러 메시징 플랫폼(WhatsApp, Telegram, Discord 등)에 자체 AI 어시스턴트를 배포할 수 있는 오픈소스 AI 어시스턴트 프레임워크입니다. Moltbook은 OpenClaw 사용자가 자체 호스팅 없이 기존 인스턴스에 참여할 수 있는 커뮤니티 기반 공유 서비스입니다. 적합한 사람: 개발자, 기술 애호가, 프라이빗 AI 어시스턴트가 필요한 팀, AI 상호작용을 직접 제어하고 싶은 사람.

Desktop(GUI)은 초보자에게 권장됩니다 - 시각적 구성, 실시간 로그, 원클릭 작업을 제공합니다. CLI가 더 적합한 경우: • 서버 배포 • 자동화 및 스크립팅 • 리소스가 제한된 환경 • 터미널 워크플로우를 선호하는 개발자 두 버전 모두 동일한 핵심 기능을 공유합니다.

최소 성공 체크리스트: 1. OpenClaw 설치 및 실행 중(상태 확인) 2. 최소 하나의 모델 API 키 구성(OpenAI, Anthropic 등) 3. 하나의 메시징 채널 연결(초보자에게는 Telegram 권장) 4. 테스트 메시지를 보내고 응답 수신 Desktop 버전으로는 보통 5-10분이 소요됩니다.

필수: • 최소 하나의 AI 모델 API 키(OpenAI, Anthropic, Google 등) 채널 연동용(최소 하나): • WhatsApp: WhatsApp이 설치된 휴대폰만 있으면 됨 • Telegram: @BotFather를 통해 봇 생성 • Discord: Discord Developer Portal에서 애플리케이션 생성 선택 사항: • 향상된 기능을 위한 웹 검색 API 키

하나의 채널로 시작하면: • 기본을 제대로 익히는 데 집중할 수 있음 • 메시지 흐름을 명확하게 이해 • 문제 디버깅이 더 쉬움 • 복잡성을 추가하기 전에 자신감 구축 익숙해지면 채널 추가는 간단합니다.

설치 후 다음을 확인하세요: 1. `openclaw health` 또는 `openclaw status`(CLI) 실행, 또는 Desktop에서 상태 확인 2. 모든 서비스에 녹색 체크 표시 확인 3. 게이트웨이에 접근 가능한지 확인(기본값: http://127.0.0.1:18789) 4. 로그에 오류 메시지가 있는지 확인 모든 확인이 통과되면 채널을 구성할 준비가 된 것입니다.

시작 문제 Top 5: 1. 포트가 이미 사용 중(다른 앱이 18789 사용) 2. API 키가 없거나 유효하지 않음 3. 권한 부족(관리자로 실행해 보세요) 4. 방화벽이 연결 차단 5. 오래된 종속성(Node.js v22+ 필요) 먼저 로그를 확인하세요 - 보통 정확한 문제를 알려줍니다.

해결책: 1. 충돌하는 프로세스를 찾아서 중지: • Mac/Linux: `lsof -i :18789` 후 `kill [PID]` • Windows (WSL): `lsof -i :18789` 후 `kill [PID]` 2. 또는 OpenClaw 포트 변경: • 시작 시 `openclaw gateway --port 18790` 사용 • 또는 onboard 시 `--gateway-port 18790` 지정

다음 단계를 순서대로 시도하세요: 1. 로그 확인: `openclaw logs --follow`로 오류 메시지 확인 2. 재구성: `openclaw configure` 실행하여 설정 재설정 3. 재설치: `npm install -g openclaw@latest` 4. 릴리스 노트에서 호환성 변경 사항 확인 5. 여전히 실패하면 로그와 함께 GitHub Issues에 보고

OpenClaw는 주로 `~/.openclaw/openclaw.json` 구성 파일로 관리됩니다. 일반적인 문제: 1. 구성 변경 후 서비스를 다시 시작하지 않음 2. 잘못된 구성 파일 경로 사용 3. JSON 구문 오류(쉼표, 따옴표 누락) 4. 환경 변수는 onboard 시 매개변수로 전달해야 함 구성 확인: `openclaw status`를 실행하여 활성 설정 확인.

레스토랑에 비유하면: • 모델 = 셰프(응답을 생성하는 AI) • 채널 = 입구(WhatsApp, Telegram 등) • 게이트웨이 = 프론트 데스크(요청을 수신하고 라우팅) • 스킬 = 특수 능력(웹 검색, 코드 실행 등) 최소 하나의 모델과 하나의 채널이 필요합니다. 게이트웨이는 자동으로 실행됩니다. 스킬은 선택적 향상 기능입니다.

가장 쉬운 방법은 대화형 설정 마법사를 실행하는 것입니다: ``` $ openclaw onboard ``` 마법사가 안내하는 내용: • AI 모델 제공자 선택(Anthropic/OpenAI 등) • API 키 입력 • 게이트웨이 서비스 설치 및 시작 설정 완료 후 `openclaw channels login telegram`으로 채널 연결. 기본 게이트웨이는 127.0.0.1:18789에 바인딩(로컬 액세스만 - 안전).

Desktop에서: 설정 → 스킬 → 토글로 전환 CLI에서: • 사용 가능한 스킬 보기: `openclaw skills list` • 스킬 설치: `openclaw skills install [skill-name]` • 스킬 활성화: `openclaw skills enable [skill-name]` 안전 팁: • 필요하지 않은 스킬 비활성화 • 활성화 전에 스킬 권한 검토 • 새 스킬은 먼저 안전한 환경에서 테스트 • 일부 스킬은 코드를 실행할 수 있음 - 주의하여 활성화

모델 전환: 1. `openclaw onboard`를 다시 실행하여 새 제공자로 재구성 2. 또는 `~/.openclaw/openclaw.json`의 agents.defaults.model 설정 편집 3. 서비스 다시 시작: `openclaw gateway status`로 확인 새 모델이 실패한 경우: • `openclaw models status`를 실행하여 모델 연결 확인 • 제공자 웹사이트에서 API 키 유효성 확인 • 모델 이름 철자 확인(예: `anthropic/claude-opus-4-5`) • 계정의 속도 제한 또는 할당량 확인

보안 체크리스트: ✓ 기본적으로 게이트웨이를 localhost(127.0.0.1)에 유지 ✓ 포트를 공개 인터넷에 직접 노출하지 않음 ✓ 원격 액세스가 필요한 경우 사용: • VPN 또는 SSH 터널 • 인증이 있는 리버스 프록시 • Cloudflare Tunnel ✓ 가능한 경우 인증 활성화 ✓ 프로덕션에서는 HTTPS 사용

다음 수정을 시도하세요: 1. 휴대폰과 컴퓨터가 같은 네트워크에 있는지 확인 2. QR 코드 새로고침(빠르게 만료됨) 3. 휴대폰의 WhatsApp을 최신 버전으로 업데이트 4. 웹 인터페이스를 사용하는 경우 브라우저 캐시 지우기 5. 밝은 환경에서 스캔 시도 6. VPN을 일시적으로 비활성화 여전히 실패하면 전화 연결 코드 방식을 시도해 보세요.

세션 문제는 보통 다음이 원인입니다: 1. 휴대폰이 오프라인 또는 절전 모드 2. 휴대폰에서 WhatsApp 로그아웃 3. 다른 기기에서 WhatsApp Web 사용 4. 네트워크 불안정 해결책: • 휴대폰을 안정적인 WiFi에 연결 • WhatsApp의 배터리 최적화 비활성화 • 다른 곳에서 WhatsApp Web 열지 않기 • WhatsApp 앱 업데이트 확인

그룹 동작은 보통 의도적입니다: • 구성에서 그룹 응답이 활성화되어 있는지 확인 • 봇이 그룹에서 응답하려면 @멘션이 필요할 수 있음 • 안전을 위해 기본 구성에서 그룹 메시지가 비활성화되어 있을 수 있음 활성화 방법: • Desktop 설정에서 그룹 응답 활성화 • 또는 `openclaw pairing`으로 그룹 권한 관리 • 먼저 소규모 그룹에서 테스트하여 정상 작동 확인

Telegram 봇은 기본적으로 프라이버시 모드가 활성화되어 있습니다: 1. @BotFather 열기 2. /mybots 전송 3. 봇 선택 4. Bot Settings → Group Privacy → Turn OFF 또는 봇을 그룹 관리자로 지정 - 관리자는 프라이버시 모드와 관계없이 모든 메시지를 볼 수 있습니다.

간단한 단계: 1. Telegram 열고 @BotFather 검색 2. /newbot 전송 3. 이름 선택(표시 이름) 4. 사용자 이름 선택('bot'으로 끝나야 함) 5. 제공된 API 토큰 복사 6. OpenClaw 구성에 토큰 추가 선택 사항: /setcommands로 명령 힌트 추가.

보통 intents 문제입니다: 1. Discord Developer Portal로 이동 2. 애플리케이션 → Bot 선택 3. 다음 Privileged Intents 활성화: • MESSAGE CONTENT INTENT • SERVER MEMBERS INTENT(필요한 경우) 4. 저장하고 봇 다시 시작 또한 확인: 봇이 채널에서 메시지 읽기 권한이 있는지.

필수 intents: • Guilds - 기본 서버 정보 • Guild Messages - 메시지 수신 • Message Content - 메시지 텍스트 읽기(특권) 선택 사항: • Guild Members - 사용자 정보(특권) • Direct Messages - DM 지원 참고: 특권 intents는 100개 이상의 서버에 있는 봇에는 인증이 필요합니다.

최소 Bot Token Scopes: • chat:write - 메시지 전송 • app_mentions:read - @멘션에 응답 • channels:history - 채널 메시지 읽기 • im:history - DM 메시지 읽기 Event Subscriptions: • message.channels • message.im • app_mention 최소한으로 시작하고 필요한 경우에만 추가하세요.

401은 인증 실패를 의미합니다. 확인 사항: 1. API 키가 올바른지(추가 공백 없음) 2. 키가 만료되거나 취소되지 않았는지 3. 키에 필요한 권한/범위가 있는지 4. 속도 제한에 도달하지 않았는지 5. 계정에 충분한 크레딧/할당량이 있는지 먼저 제공자의 API로 직접 키를 테스트하세요.

단계별 진단: 1. 모델을 직접 테스트(curl/Postman) - 느리면 모델 문제 2. 인터넷 속도와 지연 시간 확인 3. 다른 모델 시도(GPT-3.5가 GPT-4보다 빠름) 4. 제공자 상태 페이지에서 장애 확인 해결책: • 시간 초과 설정 늘리기 • 긴 응답에 스트리밍 사용 • 다른 모델 제공자 시도

로그에서 다음 패턴 확인: • 'FATAL' 또는 'PANIC' - 심각한 오류 • 'OOM' - 메모리 부족 • 'ECONNREFUSED' - 종속성에 연결할 수 없음 • 스택 트레이스 - 코드 오류 일반적인 해결책: • 메모리 할당 늘리기 • 구성 오류 수정 • 최신 버전으로 업데이트 • 외부 서비스 가용성 확인

구성 문제 해결: 1. 게이트웨이를 다시 시작했나요?(대부분의 변경에 필요) 2. JSON 파일 구문이 올바른가요?(쉼표, 따옴표 확인) 3. 올바른 구성 파일인가요?(`~/.openclaw/openclaw.json`이어야 함) 4. 게이트웨이가 실행 중인가요?(`openclaw gateway status`) 구성 확인: • `openclaw status` - 전체 상태 확인 • `openclaw models status` - 모델 연결 확인 • `openclaw health` - 상태 점검

로그 위치: • Desktop: 보기 → 로그(또는 설정 → 로그 폴더 열기) • CLI: `~/.openclaw/logs/` 또는 표준 출력 • Docker: `docker logs [컨테이너]` 주요 오류 키워드: • ERROR, FATAL, PANIC - 심각한 문제 • timeout, ETIMEDOUT - 연결 문제 • 401, 403, 429 - 인증/속도 제한 문제 • ENOENT - 파일/경로 없음

보고서에 포함할 내용: 1. OpenClaw 버전(`openclaw --version`) 2. OS 및 버전 3. 재현 단계 4. 예상 동작 vs 실제 동작 5. 관련 로그(민감한 정보 제거!) 6. 구성 스니펫(API 키 제거!) 제출처: GitHub Issues 페이지 보안 문제: 보안 담당자에게 직접 이메일

공개 노출의 위험: • 누구나 AI에 요청을 보낼 수 있음 • API 키가 추출될 수 있음 • 남용 가능성(스팸, 불법 콘텐츠) • 무단 사용으로 인한 비용 폭증 • 봇 행동에 대한 법적 책임 안전한 원격 액세스 옵션: • VPN(권장) • SSH 터널 • Cloudflare Tunnel • 인증이 있는 리버스 프록시

안전 체크리스트: 1. 공식/검증된 소스에서 온 것인가? 2. 가능한 경우 소스 코드 확인 3. 다른 사용자의 리뷰/이슈 읽기 4. 요청하는 권한 이해 5. 먼저 격리된 환경에서 테스트 위험 신호: • 불필요한 권한 요청 • 난독화/압축된 코드 • 소스 코드 없음 • 커뮤니티 피드백 없음

즉시 조치: 1. 지금 당장 제공자 웹사이트에서 키 취소 2. 새 키 생성 3. 모든 구성을 새 키로 업데이트 4. 사용 기록에서 무단 호출 확인 5. 어떻게 유출되었는지 검토(git 기록? 공개 저장소?) 예방: • 키를 git에 커밋하지 않음 • .env 파일 사용(gitignore에 추가) • 프로덕션에서는 시크릿 관리 사용

안전한 기본값: • 게이트웨이를 localhost에만 바인딩(127.0.0.1) • 기본적으로 스킬 비활성화 • 처음에는 그룹 메시지 비활성화 • 속도 제한 활성화 • 로깅 활성화(감사용) • 채널 봇에 최소 권한 기억하세요: 제한적으로 시작하고 필요한 경우에만 완화.