자주 묻는 질문
실제 환경 설정(로컬 개발, VPS, 다중 에이전트, OAuth/API 키, 모델 페일오버)에 대한 빠른 답변과 심층적인 문제 해결을 제공합니다. 런타임 진단은 문제 해결을 참고하십시오. 전체 구성 레퍼런스는 구성을 참고하십시오.목차
- [빠른 시작 및 최초 실행 설정]
- 막혔어요. 가장 빠르게 해결하는 방법은 무엇인가요?
- OpenClaw를 설치하고 설정하는 권장 방법은 무엇인가요?
- 온보딩 이후 대시보드는 어떻게 여나요?
- localhost 와 원격에서 대시보드 토큰은 어떻게 인증하나요?
- 필요한 런타임은 무엇인가요?
- Raspberry Pi 에서 실행되나요?
- Raspberry Pi 설치 팁이 있나요?
- ‘wake up my friend’ 에서 멈추고 온보딩이 진행되지 않습니다. 어떻게 해야 하나요?
- 온보딩을 다시 하지 않고 새 머신(Mac mini)으로 이전할 수 있나요?
- 최신 버전의 변경 사항은 어디에서 보나요?
- docs.openclaw.ai 에 접근할 수 없습니다(SSL 오류). 어떻게 하나요?
- stable 과 beta 의 차이는 무엇인가요?
- beta 버전은 어떻게 설치하며 beta 와 dev 의 차이는 무엇인가요?
- 최신 빌드를 사용해 보려면 어떻게 하나요?
- 설치와 온보딩에는 보통 얼마나 걸리나요?
- 설치 프로그램이 멈췄나요? 더 많은 피드백을 얻으려면?
- Windows 설치 시 git 을 찾을 수 없거나 openclaw 가 인식되지 않습니다
- 문서에서 답을 찾지 못했습니다. 더 나은 답을 얻으려면?
- Linux 에 OpenClaw 를 설치하려면 어떻게 하나요?
- VPS 에 OpenClaw 를 설치하려면 어떻게 하나요?
- 클라우드/VPS 설치 가이드는 어디에 있나요?
- OpenClaw 에게 스스로 업데이트하도록 요청할 수 있나요?
- 온보딩 마법사는 실제로 무엇을 하나요?
- 이걸 실행하려면 Claude 또는 OpenAI 구독이 필요한가요?
- API 키 없이 Claude Max 구독을 사용할 수 있나요?
- Anthropic “setup-token” 인증은 어떻게 동작하나요?
- Anthropic setup-token 은 어디에서 찾나요?
- Claude 구독 인증(Claude Pro 또는 Max)을 지원하나요?
- Anthropic 에서
HTTP 429: rate_limit_error가 표시되는 이유는 무엇인가요? - AWS Bedrock 을 지원하나요?
- Codex 인증은 어떻게 동작하나요?
- OpenAI 구독 인증(Codex OAuth)을 지원하나요?
- Gemini CLI OAuth 는 어떻게 설정하나요?
- 가벼운 대화에 로컬 모델을 사용해도 괜찮나요?
- 호스팅된 모델 트래픽을 특정 리전에 유지하려면 어떻게 하나요?
- 설치하려면 Mac Mini 를 꼭 사야 하나요?
- iMessage 지원을 위해 Mac mini 가 필요한가요?
- OpenClaw 를 실행하기 위해 Mac mini 를 구매하면 MacBook Pro 에 연결할 수 있나요?
- Bun 을 사용할 수 있나요?
- Telegram:
allowFrom에 무엇을 넣어야 하나요? - 여러 사람이 서로 다른 OpenClaw 인스턴스에서 하나의 WhatsApp 번호를 사용할 수 있나요?
- ‘빠른 채팅’ 에이전트와 ‘코딩용 Opus’ 에이전트를 동시에 실행할 수 있나요?
- Linux 에서 Homebrew 가 동작하나요?
- 해커블(git) 설치와 npm 설치의 차이는 무엇인가요?
- 나중에 npm 과 git 설치를 전환할 수 있나요?
- Gateway 를 노트북에서 실행해야 하나요, 아니면 VPS 에서 실행해야 하나요?
- OpenClaw 를 전용 머신에서 실행하는 것이 얼마나 중요한가요?
- 최소 VPS 요구 사항과 권장 OS 는 무엇인가요?
- VM 에서 OpenClaw 를 실행할 수 있나요? 요구 사항은 무엇인가요?
- OpenClaw 란 무엇인가요?
- Skills 와 자동화
- 리포지토리를 더럽히지 않고 Skills 를 커스터마이즈하려면 어떻게 하나요?
- 커스텀 폴더에서 Skills 를 로드할 수 있나요?
- 작업별로 서로 다른 모델을 사용하려면 어떻게 하나요?
- 무거운 작업 중에 봇이 멈춥니다. 이를 오프로딩하려면?
- Cron 또는 알림이 실행되지 않습니다. 무엇을 확인해야 하나요?
- Linux 에서 Skills 를 설치하려면 어떻게 하나요?
- OpenClaw 가 일정에 따라 또는 백그라운드에서 지속적으로 작업을 실행할 수 있나요?
- Linux 에서 Apple macOS 전용 Skills 를 실행할 수 있나요?
- Notion 또는 HeyGen 통합이 있나요?
- 브라우저 제어를 위한 Chrome 확장 프로그램은 어떻게 설치하나요?
- 샌드박스화와 메모리
- 디스크 상의 위치
- 구성 기본
- 설정 파일 형식은 무엇인가요? 어디에 있나요?
- gateway.bind: “lan” (또는
"tailnet")을 설정했더니 아무것도 리슨하지 않고 UI 에서 unauthorized 가 표시됩니다 - 왜 이제 localhost 에서도 토큰이 필요한가요?
- 구성을 변경한 후 재시작해야 하나요?
- 웹 검색(및 웹 가져오기)을 활성화하려면 어떻게 하나요?
- config.apply 가 구성을 지웠습니다. 어떻게 복구하고 방지하나요?
- 여러 디바이스에 걸쳐 전문화된 워커와 함께 중앙 Gateway 를 실행하려면 어떻게 하나요?
- OpenClaw 브라우저를 헤드리스로 실행할 수 있나요?
- 브라우저 제어에 Brave 를 사용하려면 어떻게 하나요?
- 원격 Gateway 와 노드
- Telegram, Gateway, 노드 간에 명령은 어떻게 전파되나요?
- Gateway 가 원격에 호스팅된 경우 에이전트가 내 컴퓨터에 어떻게 접근하나요?
- Tailscale 이 연결되었지만 응답이 없습니다. 어떻게 하나요?
- 두 개의 OpenClaw 인스턴스가 서로 통신할 수 있나요(로컬 + VPS)?
- 여러 에이전트에 대해 별도의 VPS 가 필요한가요?
- VPS 에서 SSH 하는 대신 개인 노트북에 노드를 사용하는 이점이 있나요?
- 노드는 Gateway 서비스를 실행하나요?
- 구성을 적용하는 API / RPC 방식이 있나요?
- 첫 설치를 위한 최소한의 ‘합리적인’ 구성은 무엇인가요?
- VPS 에서 Tailscale 을 설정하고 Mac 에서 연결하려면 어떻게 하나요?
- Mac 노드를 원격 Gateway 에 연결하려면 어떻게 하나요(Tailscale Serve)?
- 두 번째 노트북에 설치해야 하나요, 아니면 노드를 추가하면 되나요?
- 환경 변수와 .env 로딩
- 세션과 다중 채팅
- 새로운 대화를 시작하려면 어떻게 하나요?
/new를 보내지 않으면 세션이 자동으로 초기화되나요?- 여러 OpenClaw 인스턴스로 하나의 CEO 와 여러 에이전트 팀을 만들 수 있나요?
- 작업 도중 컨텍스트가 잘렸습니다. 어떻게 방지하나요?
- 설치를 유지한 채 OpenClaw 를 완전히 초기화하려면 어떻게 하나요?
- “context too large” 오류가 발생합니다. 어떻게 초기화 또는 압축하나요?
LLM request rejected: messages.N.content.X.tool_use.input: Field required오류가 발생하는 이유는 무엇인가요?- 30분마다 하트비트 메시지가 오는 이유는 무엇인가요?
- WhatsApp 그룹에 “봇 계정” 을 추가해야 하나요?
- WhatsApp 그룹의 JID 는 어떻게 얻나요?
- 그룹에서 OpenClaw 가 응답하지 않는 이유는 무엇인가요?
- 그룹/스레드는 다이렉트 메시지와 컨텍스트를 공유하나요?
- 워크스페이스와 에이전트는 몇 개까지 만들 수 있나요?
- Slack 에서 여러 봇 또는 채팅을 동시에 실행할 수 있나요? 설정은 어떻게 하나요?
- 모델: 기본값, 선택, 별칭, 전환
- “기본 모델” 이란 무엇인가요?
- 어떤 모델을 권장하나요?
- 구성을 지우지 않고 모델을 전환하려면 어떻게 하나요?
- 자가 호스팅 모델(llama.cpp, vLLM, Ollama)을 사용할 수 있나요?
- OpenClaw, Flawd, Krill 은 어떤 모델을 사용하나요?
- 재시작 없이 즉시 모델을 전환하려면 어떻게 하나요?
- 일상 작업에는 GPT 5.2 를, 코딩에는 Codex 5.3 을 사용할 수 있나요?
- “Model … is not allowed” 가 표시되고 응답이 없는 이유는 무엇인가요?
- “Unknown model: minimax/MiniMax-M2.1” 이 표시되는 이유는 무엇인가요?
- 기본값으로 MiniMax 를 사용하고 복잡한 작업에는 OpenAI 를 사용할 수 있나요?
- opus / sonnet / gpt 는 내장 단축키인가요?
- 모델 단축키(별칭)를 정의/재정의하려면 어떻게 하나요?
- OpenRouter 또는 Z.AI 와 같은 다른 프로바이더의 모델을 추가하려면 어떻게 하나요?
- 모델 페일오버와 “All models failed”
- 인증 프로필: 개념과 관리 방법
- Gateway: 포트, “이미 실행 중”, 원격 모드
- Gateway 는 어떤 포트를 사용하나요?
- 왜
openclaw gateway status는Runtime: running이지만RPC probe: failed인가요? - 왜
openclaw gateway status에서Config (cli)와Config (service)가 다르게 표시되나요? - “another gateway instance is already listening” 은 무엇을 의미하나요?
- 원격 모드에서 OpenClaw 를 실행하려면 어떻게 하나요(클라이언트가 다른 곳의 Gateway 에 연결)?
- Control UI 에서 “unauthorized” 가 표시되거나 계속 재연결됩니다. 어떻게 하나요?
gateway.bind: "tailnet"를 설정했는데 바인딩되지 않거나 아무것도 리슨하지 않습니다- 같은 호스트에서 여러 Gateway 를 실행할 수 있나요?
- “invalid handshake” / code 1008 은 무엇을 의미하나요?
- 로깅과 디버깅
- 로그는 어디에 있나요?
- Gateway 서비스를 시작/중지/재시작하려면 어떻게 하나요?
- Windows 에서 터미널을 닫았습니다. OpenClaw 를 어떻게 재시작하나요?
- Gateway 는 실행 중이지만 응답이 오지 않습니다. 무엇을 확인해야 하나요?
- “Disconnected from gateway: no reason” - 어떻게 하나요?
- Telegram setMyCommands 가 네트워크 오류로 실패합니다. 무엇을 확인해야 하나요?
- TUI 에 출력이 없습니다. 무엇을 확인해야 하나요?
- Gateway 를 완전히 중지했다가 다시 시작하려면 어떻게 하나요?
- ELI5:
openclaw gateway restartvsopenclaw gateway - 무언가 실패할 때 더 많은 세부 정보를 가장 빠르게 얻는 방법은 무엇인가요?
- 미디어와 첨부 파일
- 보안과 접근 제어
- 채팅 명령, 작업 중단, “멈추지 않습니다”
문제가 있을 때 처음 60초
-
빠른 상태 확인 (첫 점검)
빠른 로컬 요약: OS + 업데이트, gateway/service 접근성, agents/sessions, provider 구성 + 런타임 문제 (gateway 가 접근 가능한 경우).
-
공유 가능한 보고서 (안전)
로그 꼬리 포함 읽기 전용 진단 (토큰은 마스킹됨).
-
데몬 + 포트 상태
supervisor 런타임 vs RPC 접근성, 프로브 대상 URL, 서비스가 사용했을 가능성이 높은 config 표시.
-
심층 프로브
gateway health checks + provider probes 실행 (gateway 접근 필요). Health 참고.
-
최신 로그 추적
RPC 가 다운된 경우 다음으로 대체:파일 로그는 서비스 로그와 분리되어 있습니다. Logging 및 문제 해결을 참고하십시오.
-
Doctor 실행 (복구)
config/state 복구 및 health checks 실행. Doctor 참고.
-
Gateway 스냅샷
실행 중인 gateway 에 전체 스냅샷을 요청합니다 (WS 전용). Health 참고.
스크린샷/채팅 로그의 정확한 질문에 대한 답변
Q: “API 키를 사용할 때 Anthropic의 기본 모델은 무엇인가요?” A: OpenClaw에서는 자격 증명과 모델 선택이 분리되어 있습니다.ANTHROPIC_API_KEY를 설정하거나(또는 auth 프로필에 Anthropic API 키를 저장하면) 인증이 활성화되지만, 실제 기본 모델은 agents.defaults.model.primary에 구성한 값입니다 (예: anthropic/claude-sonnet-4-5 또는 anthropic/claude-opus-4-6). No credentials found for profile "anthropic:default"가 표시된다면, 실행 중인 에이전트에 대해 게이트웨이가 예상 위치의 auth-profiles.json에서 Anthropic 자격 증명을 찾지 못했다는 의미입니다.
아직 해결되지 않았나요? Discord에서 질문하거나 GitHub discussion을 열어주세요.